---
name: unified-auth-signin
description: >-
  Add "Sign in with …" to an application using the Unified.to Authentication
  API, so users log in with Google, Microsoft, and other OAuth2 or SAML
  providers and are verified by a signed JWT. Use when a coding task involves
  social login, single sign-on (SSO), or verifying a user's identity via a third
  party — not creating data connections.
license: MIT
metadata:
  category: auth
  api_base: https://api.unified.to
  docs: https://docs.unified.to/auth/overview
---

# Add "Sign in with Unified" to your app with the Unified.to Authentication API

The Unified Authentication API lets your users sign in to your application with
OAuth2 or SAML providers (Google, Microsoft, and more). Unlike the rest of the
Unified APIs, this flow is about **identity, not data connections** — you get a
signed JWT with the user's verified name and emails.

> Authentication-only integrations are for signing in users. Do **not** use them
> to create data connections. To authorize customers and create connections,
> use the standard authorization flow instead
> (https://docs.unified.to/tutorials/customize-auth-flow).

## When to use this skill

Use this skill when the task is to:

- Add social / OAuth2 login (e.g. "Sign in with Google")
- Add SAML single sign-on (SSO)
- Verify a user's identity through a third-party provider

## Prerequisites

1. A Unified.to workspace with a **Workspace ID** and a **Workspace Secret**
   (`app.unified.to` → Settings → API). The **secret** is used to verify the
   JWT — keep it server-side only, never in the browser.
2. Activated auth/SAML integrations at
   https://app.unified.to/integrations?tab=auth (or `tab=saml`).

## The flow

1. **Show sign-in links.** Either configure the embedded sign-in widget at
   https://app.unified.to/settings/embed, or fetch the activated auth
   integrations and build a sign-in URL per provider.
2. **Redirect the user** to the sign-in URL.
3. **Verify the returned JWT** on your server using your Workspace Secret, then
   log the user in.

### 1. List activated auth integrations (optional)

```
GET https://api.unified.to/unified/integration?categories=auth
Authorization: Bearer YOUR_API_KEY
```

Each result has at least `name`, `type`, and `logo_url`:

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

### 2. Build the sign-in URL

**OAuth2 login:**

```
https://api.unified.to/unified/integration/auth/{workspace_id}/{integration_type}?redirect=true
```

**SAML SSO login:**

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

Optional query parameters:

| Parameter          | Purpose                                                            |
| ------------------ | ----------------------------------------------------------------- |
| `redirect=true`    | Redirect the user. Omit to get the URL back as a string instead.  |
| `success_redirect` | Where to send the user after a successful sign-in.                |
| `failure_redirect` | Where to send the user on error.                                  |
| `state`            | An opaque string echoed back to `success_redirect` (e.g. a nonce).|

Send the user to this URL (a link or a redirect) to start sign-in.

### 3. Verify the login (server-side)

After a successful sign-in the user is redirected back (to `success_redirect`)
with a `jwt` query parameter — a JWT signed with your **Workspace Secret**.
Verify it on your server:

```javascript
import jwt from 'jsonwebtoken';

// req.query.jwt came back on your success_redirect URL
try {
    const user = jwt.verify(req.query.jwt, process.env.UNIFIED_WORKSPACE_SECRET);
    // user => { name: 'Jane Smith', emails: ['jane@foo.com', 'jsmith89@gmail.com'] }
    // Use a verified email to sign the user into your application.
} catch (err) {
    // Invalid / tampered token — reject the sign-in.
    console.error(err);
}
```

Never verify the JWT in the browser — the Workspace Secret must stay on your
server.

## Notes

- The decoded JWT contains at least `name` and `emails`. Use a verified email to
  match or create the user account in your system.
- For a customized authorization/connection flow (not sign-in), see
  https://docs.unified.to/tutorials/customize-auth-flow.
- For OAuth2 background, see
  https://docs.unified.to/guides/understanding_oauth2_authorization_flows.

## References

- Auth API overview: https://docs.unified.to/auth/overview
- Embedded sign-in / authorization components: https://docs.unified.to/concepts/embedded-components
- Source guide: https://docs.unified.to/guides/use_unified_to_sign_in_your_users_into_your_application