Authentication API

Allow your application to sign-in your users with an OAuth2 integration. There are two ways to use the authentication APIs:

  • Redirect your user to the Login endpoint with a specific integration_type and your workspace_id
  • Call the Integrations API endpoint with categories=auth to get a list of authentication integrations and use the oauthUrl field in each object to redirect your user

Authentication-only integrations should not be used to create connections. They are intended to sign in your users. If you're trying to authorize your customers and create connections on your own, refer to our tutorial: Customize your authorization flow with the Unified API.

Instructions

1. Activate authentication integrations

Go to https://app.unified.to/integrations?tab=auth and activate integrations that you would like to have your users sign-in to your application with

2. Display Sign-in links to your users

2.1. Use our embedded Embedded Sign-in widget

Go to https://app.unified.to/settings/embed and configure our embedded sign-in widget.

2.2. Use our getActivatedIntegrations API

Call the getActivatedIntegrations API endpoint to retrieve a list of activated authentication integrations categories=auth.

[
    {
        logo_url: 'https://api.unified.to/docs/images/google.png',
        name: 'Google',
        type: 'google',
        oauthUrl: 'https://....',
    },
];

The Sign-in URL can have the following optional parameters:

redirect=trueredirect the user or if empty, will return the URL as string in its response
success_redirectthe URL that the user will be redirected to once they have successfully authenticated with that integration vendor
failure_redirectthe URL that the user will be redirected to if there is an error or other issue preventing the user from being authenticated by the integration vendor
statea string that will be sent back to the success_redirect. You can use this to remember a user ID or other identifier.

3. Verify the login

Once the user successfully signs-in, they are redirected back to your application (or to the location of the success_redirect URL parameter from step 2).

A jwt parameter will be appended to that URL. The jwt is a base64 encoded JWT and is signed with your Workspace Secret found at https://app.unified.to/settings/api.

Verify the JWT with your workspace secret on your server (NOT in your browser as the workspace secret is not public).

Example code to verify a JWT on a NodeJS server:

try {
    let result = JWT.verify(req.payload.jwt, workspace.secret);
} catch (err) {
    console.error(err);
}

The decoded JWT will contain name and emails field:

{
    "name": "Jane Smith",
    "emails": ["jane@foo.com", "jsmith89@gmail.com"]
}

Use the emails to log the user into your application as it is verified by the integration.

Are we missing anything? Let us know
Was this page helpful?