Authentication

You can configure apps to remember user data, using either the auth.getCanvaUserToken API or connecting with a third-party platform. This approach can make certain features and content available only to authenticated users, or a limited subset of users.

This article contains some guidelines for creating an efficient authentication flow.

Canva's users want to quickly evaluate an app's value, and might be deterred from using your app if you require them to log in before they can see its functionality.

An efficient authentication workflow can produce a better experience for your users and subsequently lead to more app usage. For example, if your app requires the user to log in just so that you can see data about who is using your app, consider using frictionless authentication instead of requiring a separate login.

When implementing an authentication workflow in your app, we recommend referring to the following list, where appropriate. Workflows are listed in order of preference, so if your app uses workflows shown higher on the list, the better the user experience.

1. All functions are available to the user. No authentication required.
2. All functions are available to the user, regardless of whether the user authenticates.
3. Some functions are available to the user, but they can still complete a basic workflow. The user must log in to use the other functions.
4. Some functions are available to the user to evaluate the app, but they cannot complete a workflow. The user must log in to complete the workflow.
5. No functions are available unless the user authenticates.

For each of the above options, you can use frictionless authentication. This is the preferred authentication approach when you want to track user data (such as time or usage), recognize returning users, or implement a freemium model.

An app can quickly demonstrate its usefulness when it's promoted in the Apps Marketplace, such as being included in the Featured apps section.

However, an app is not eligible to be featured unless a user can test functionality before manual authentication occurs in the workflow. This means that only apps that have no authentication or those that include a timed or per-use trial can be featured apps.

• Make it easy for the user to benefit from the app. Where possible, make the app useful before the user has to authenticate.
• Authentication flows must occur in the authentication pop-up window, not within the app's iframe. The sign-up and login forms must only appear in the pop-up window.
• Start an authentication flow by calling the requestAuthentication method. This will display a screen with a Connect button. Don't show redundant authentication screens before this screen or attempt to bypass the standard authentication flow.
• Prevent users from arriving at dead-ends or becoming stuck in endless loops.
• Support non-desktop devices, such as mobile phones and tablets.
• Do not auto-subscribe users to marketing content — all marketing material must be opt-in.
• If the same user installs the same app under different teams⁠(opens in a new tab or window), require them to authenticate separately for each team — do not automatically authenticate the user.
• Ensure that users are able to disconnect your app, and that the disconnection is handled appropriately. This is described in the next section.

Users can choose to remove your app from their account, and the app must respect the user's intention to no longer be associated with the app. Users are also free to change their minds and reconnect your app later.

• Do log users out of your app when they remove it.
• Do require users to reauthenticate if they reconnect your app.

For a consistent user experience, handle these events using the following flow.

When the user clicks Remove from your apps:

1. Log the user out of your app.
2. Delete the connection between your app and the third-party platform.

If the user later reconnects your app:

1. Display the initial page that prompts them to open the app.
2. Immediately redirect the user to the connection page.
3. When the user clicks on Connect, the app must require them to re-enter their credentials and log in with the app.
4. After successfully logging in, users must be able to use the app right away.

• If you're using frictionless authentication, see Handle disconnections.
• If you're using OAuth, see Revoking access.
• If you're using manual authentication, see Handle disconnections.

• For the pop-up page, use the title HTML element⁠(opens in a new tab or window) to set a meaningful title on the authentication's pop-up window.
• Provide clear and actionable error messages.
• Ensure that the redirect URL appears familiar and friendly — that is, not like a phishing threat.
• Provide options for both signing up for and logging in to the platform.

If some of your app's features don't require authentication, users should be able to use the app without entering credentials right away. Allowing immediate access helps maintain design productivity, reduces friction, and defers authentication until it's genuinely required. For example:

• Freemium apps: Authentication is optional for apps using a freemium model. We encourage apps with paid features to use a freemium experience, which allows the user to try the features to understand the value, and authenticate later in the workflow to access full features.
• Content publisher apps: It's necessary for publish apps to implement deferred authentication. This allows the user to enter publish settings, preview, and then authenticate to decide which account to publish with.

When building authentication flows in your app, you must implement error handling. Clear and concise error messages can help users understand what went wrong and what to do next.

At a minimum, your app should render a defensive catch-all fallback and a server error view. You can then sequentially add more error handling scenarios depending on your app's circumstances. The error message should also follow our error messaging best practices.

The following UI guidelines explain recommended practices for required error messaging scenarios (the catch-all fallback and server errors) as well as other optional error scenarios.

Required — The fallback view for all errors. It informs users that authentication has failed. Its message is simple and generic. Users can fix the error by trying again. The fallback is also a safety net for any unforeseen errors.

1. A Keep the message short, informing users that the connection has failed.

2. B State your app name because your app could appear in surfaces where the app header isn't immediately visible.

3. C Use the primary button to ask users to try reconnecting.

4. D Provide a way to go back to the app's starting step to use the app in its unauthenticated state.

• Use technical jargon.
• Blame the user, and use a written tone that implies the user is at fault.

Required — This occurs when there's an unexpected server-side issue that the user can't resolve. We recommend letting the user know that authentication has failed and to try again later.

• Acknowledge the issue, and clearly state that a server error has occurred.
• Reassure the user, and let them know the issue is being addressed.
• Tell the user to come back later.

• Share unnecessary technical details with the user.
• Blame the user, and use a written tone that implies the user is at fault.

Optional — This occurs when the user hasn't granted the permissions necessary for app features to work. Handling this error is only required if your app asks users for specific permissions. For example, your app's features might cause progressive permission requests.

1. A Provide instructions to retry and grant specific permissions.

2. B If your app's permissions are complex, offer assistance and a link to a guide.

• Avoid vague requests. Make sure you explain why you are asking for the required permissions.
• Overload the error message with too much information. Provide a link to external content.

Optional — This error occurs when there's a server overload. Use this error message if you expect your server to frequently experience excessive load. For example, a freemium Gen AI app that allocates fewer resources to their free users.

• Focus on transparency, explaining that the server is busy.
• Provide a primary action to try again soon.

• Include technical details irrelevant to the design task.

Optional — These are error types specific to your app, or unexpected and hard to predict error scenarios.

For example, a private app might limit an external contractor's access. When a time limit expires, the contractor sees an error message explaining why they can't continue accessing the app. The error message offers a way for them to extend their access, such as a support request.

Only build this error message view if there's no way to prevent these specific errors in your app. During the app review process, other error messages are reviewed on a case-by-case basis because we have limited knowledge of your specific error types.

• Add a help link to your support page if your support team can address the error.
• Follow the error and messaging design guidelines.

• Build this error message if the catch-all feedback provides sufficient support for your app error scenarios.

If your app lets the user switch between multiple accounts, we recommend you use the Account Switcher pattern⁠(opens in a new tab or window) from the App UI Kit. This pattern allows the user to switch, add, and manage accounts, as well as handle edge cases such as reconnecting expired accounts.

There are multiple ways to allow users to access the Account Switcher in your app. If you're using the recommended pattern, you can control this using the trigger prop in FlyoutMenu.

Although we don't have strict requirements for the entry point, we recommend using one of the following common patterns:

If your app is integrated with multiple providers, we recommend the following design patterns for different authentication requirements.

Your app may limit access to certain functions without authentication, but users can complete the workflow. For example, freemium apps with both free and paid features, or limited free AI credits, or a data app with both public and private datasets. The general guidance is to keep the users focused on the primary workflow, and only require authentication when they need to access protected content.

1. A Use a secondary trigger to open a flyout⁠(opens in a new tab or window) with the list of providers. It should be placed after the primary button so the user can use the app until they need to authenticate.

2. B After the user authenticates, you should provide a UI to disconnect or switch accounts in the same proximity as the trigger button.

• Show all the providers without progressive disclosure. This overloads the UI with too many options.

Your app allows the user to use some of its functions, but they must authenticate to complete the workflow. For example, social media publish apps allow the user to add captions and preview their content, but they must authenticate to publish the design. The general guidance is to maintain the user's design productivity until they need to authenticate at the end.

1. A Use a primary 'Connect' button to trigger a flyout with the list of providers.

2. After the user authenticates:

   1. B Add a secondary UI, such as an Account Switcher, to show they are authenticated and can disconnect or switch accounts.

   2. C Make sure there's one new primary button to complete the workflow.

• Show multiple primary buttons. This competes with the primary workflow.

When no functions are available unless the user authenticates, we recommend you to render a simple screen listing all the authentication providers. This focuses the user on authenticating, and defers the app's functionality to the next step.

• Simplify the UI by showing a clear message to direct the user to choose a provider to authenticate.

• Clutter the UI with elements that are not relevant to the authentication flow.

There can be many scenarios to consider when building an authentication flow. You are free to make your own written content to communicate authentication flows. Alternatively, to speed up your development, we've provided some suggested written content that you can use.