Authorization

Updated: October 16, 2026

Authorization is the process of asking customers to authorize access to their third-party accounts.

Unified provides several options to accomplish this, from easy 1-line embedded components to a full-featured API, and even CNAMEd domains.

Embedded Authorization Component

Unified.to provides a suite of pre-built front-end authorization components that support React, Angular, Vue, and Svelte (and plain JavaScript) for you to use in your app.

These authorization components display a list of your activated integrations, returned directly from our API. Once the end-user clicks on an integration, they will be redirected to the authorization page for that integration, regardless if it is OAuth2, API Token and any other type of authorization. in their File Storage connection.

Instructions

To use any one of these components in your app:

• Make sure you've activated some integrations first. You can do so at app.unified.to/integrations.
• On app.unified.to, click on Embedded components and select which of the widgets you want to use from the tab.
• Configure how you want the component to behave under the Configuration tab.
• View and copy the code to add to your app under the Embedded Code tab.
• Important: Under the Options tab, be sure to select the correct permissions scopes that the integrations you activated are expecting to receive. By leaving these options blank, Unified.to will request access to all possible scopes. To learn more about scopes, see: Understanding scopes.

Front-end Frameworks

Manually Authorizing Connections

If you do not want to use our pre-built authorization components, nor want to copy our component source code and make changes, then you can use our API

This is the flow to follow in your application with your end-user:

1. You redirect your user to our authorization URL. Make sure to include a success_redirect, failure_redirect, and permissions. Also include either state or external_xref.
2. Your end-user will authorize the connection
3. If they cancel, then we return them to the failure_redirect
4. If they authorize the connection, we then test their API credentials to see if it has the valid permissions
5. If that fails, then we redirect them back to the failure_redirect and also include an error message with a string denoting the error
6. If it succeeds, then we redirect them to the success_redirect and add additional parameters to the URL

Successful authorization

If the authorization is successful (either via our authorization components or via the API), we redirect the user to the specified success_redirect URL and add the following URL parameters:

• id: the connection ID (the newly created connection, or the same existing connection when re-authorizing)
• state: the state value you provided
• nonce: a random nonce value
• type: the integration type of connection
• sig: a security signature to ensure that this information has not been tampered with;

Signature calculation

The signature is calculated as follows:

sig = HmacSha256(workspace.secret).update(connection.id).update(nonce).update(state).digest('hex');

Re-authorize an existing connection

When a connection becomes unhealthy because its credentials were revoked or expired (for example, a CONNECTION_UNHEALTHY event with an HTTP 401), ask your end-user to re-authorize the same connection instead of creating a new one. The connection keeps its ID, so your stored connection IDs, webhooks, and external_xref keep working.

1. From your backend, create a re-authorization token with your API key using Create a re-authorization token for a connection:
   curl -X POST https://api.unified.to/unified/connection/{connection_id}/reauth \
       -H "Authorization: bearer {your_api_key}"
   

   { "reauth_token": "6650...e1.9f2c...", "expires_at": "2026-10-01T17:45:00.000Z" }
   

2. Redirect your end-user to the usual authorization URL, adding connection_id and reauth_token:
   https://api.unified.to/unified/integration/auth/{workspace_id}/{integration_type}
       ?connection_id={connection_id}
       &reauth_token={reauth_token}
       &success_redirect=...
       &failure_redirect=...
   

3. Your end-user signs in to the integration again. We test the new credentials the same way as for a new connection.
4. If it succeeds, we update the existing connection and redirect to success_redirect with the same id. You also receive a CONNECTION_UPDATED webhook (and CONNECTION_HEALTHY if the connection was unhealthy). No CONNECTION_CREATED event is sent.

Things to know:

• The token is single-use and expires after 30 minutes. Create it right before you send the end-user to the authorization URL. If you email the link, create a fresh token when the end-user clicks it rather than embedding one in the email.
• connection_id and reauth_token must be sent together, for the same connection, integration, and environment (env) the token was created for.
• If the token is missing, invalid, expired, or already used, we redirect to failure_redirect with error=authorization error: invalid or expired re-authorization link (or return a 400 when there is no failure_redirect). Create a new token and try again.
• If the end-user cancels or the credential test fails, the token is not used up, so they can retry with the same link until it expires.
• Without a scopes parameter, re-authorizing asks for the permissions the connection already has, and its permissions and categories stay unchanged. Pass scopes to change them; the categories then come from your activated integration, as they do for new connections.
• A paused connection stays paused after re-authorizing.

Other Embedded Components

Unified also has non-authorization components that you can embed into your app. These components are:

• Sign-in: Authenticate users so they can sign into your app; info
• Public Directory: Display a list of your integration so your users can learn about your third-party API offerings; info
• FileManager: Display a list of files in a directory so your users can pick a file; info
• CalendarScheduler: Display a calendar so your users can schedule events in their Calendar connection; info
• MessagingManager: Display a list of channels/folders and messages; info