Authentication API

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

• Redirect your user to the OAuth2 login endpoint / SAML SSO endpoint with a specific integration_type and your workspace_id
• Call the Integrations API endpoint with categories=auth,saml to get a list of authentication integrations, then construct the sign-in URL for each integration:

For OAuth2 login:

https://api.unified.to/unified/integration/login/{workspace_id}/{integration.type}?redirect=true

For SAML SSO login:

https://api.unified.to/unified/integration/saml/{workspace_id}/{integration.type}?redirect=true

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. That flow uses /unified/integration/auth/... and returns a connection id, not a login JWT.

Instructions

1. Activate authentication integrations

Go to https://app.unified.to/integrations?tab=auth or https://app.unified.to/integrations?tab=saml 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 (OAuth2-only)

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 or categories=saml.

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

Construct the sign-in URL from your workspace_id and each integration's type:

For OAuth2 login:

https://api.unified.to/unified/integration/login/{workspace_id}/{integration.type}?redirect=true

For SAML SSO login:

https://api.unified.to/unified/integration/saml/{workspace_id}/{integration.type}?redirect=true

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

2.3. Restrict sign-in redirect hosts

A forwarded sign-in link can otherwise be edited so the login JWT is sent to someone else's site. If you leave out success_redirect, Unified uses the page the user came from, so any page that links to your sign-in URL would receive the JWT too. Set trusted_domains on the workspace to the hostnames allowed for success_redirect and failure_redirect (for example app.yourcompany.com or localhost:3000).

When trusted_domains is set, Unified rejects a redirect whose host is not on that list (400). Redirects must be absolute URLs. If trusted_domains is empty or unset, redirect hosts are not restricted.

Update your workspace with a user API key that belongs to a workspace admin. Include your workspace name:

PUT https://api.unified.to/unified/workspace
Authorization: Bearer YOUR_API_KEY

{ "name": "Your workspace", "trusted_domains": ["app.yourcompany.com"] }

Entries are saved as lowercase hosts; a full URL such as https://app.yourcompany.com/login is saved as app.yourcompany.com. Wildcards (*.yourcompany.com) are rejected, so list each host.

The same list also applies to connection authorization (/unified/integration/auth/...). See Customize your authorization flow.

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). Then check:

• redirect is your own callback URL (compare origin and path, so per-request query parameters still match).
• state matches what you stored for this browser session when you created the sign-in link. This stops someone from replaying a JWT they obtained into their own browser.

The JWT expires 10 minutes after it is issued (exp), so exchange it for your own session right away and don't store it as a session token.

Example code to verify a JWT on a NodeJS server:

const EXPECTED_CALLBACK = 'https://app.yourcompany.com/login/callback';

try {
    const result = JWT.verify(req.query.jwt, workspace.secret); // also checks exp

    const landed = new URL(result.redirect);
    const expected = new URL(EXPECTED_CALLBACK);
    if (landed.origin !== expected.origin || landed.pathname !== expected.pathname) {
        throw new Error('Unexpected redirect');
    }
    if (!result.state || result.state !== req.session.signinState) {
        throw new Error('Unexpected state');
    }
    // sign the user in with a verified email from result.emails
} catch (err) {
    console.error(err);
}

The decoded JWT contains workspace_id, name, emails, state, redirect (the success_redirect URL used), and the standard iat, exp and jti claims:

{
    "workspace_id": "5e8ba11d3fb8ff95c90b7332",
    "name": "Jane Smith",
    "emails": ["jane@foo.com", "jsmith89@gmail.com"],
    "state": "optional-state-from-signin-url",
    "redirect": "https://app.yourcompany.com/login/callback",
    "iat": 1760300000,
    "exp": 1760300600,
    "jti": "3f0c6f9e-6d7e-4c6b-9a43-2b1f1c0d7e55"
}

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