> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Authorization

Send a user to connect their account, then confirm they are the user your app meant. The steps and when to use each option are in [Authorize a user](https://docs.scalekit.com/agentkit/tools/authorize/) and [Verify users](https://docs.scalekit.com/agentkit/user-verification/).

One page per endpoint, each with its own markdown copy:

| Endpoint | Request | What it does | Python SDK | Node.js SDK |
| --- | --- | --- | --- | --- |
| [Get an authorization link](https://docs.scalekit.com/agentkit/reference/authorization/get-an-authorization-link.md) | `POST /api/v1/connected_accounts/magic_link` | Create the one-time link a user opens to connect their account. | `actions.get_authorization_link` | `actions.getAuthorizationLink` |
| [Verify the user](https://docs.scalekit.com/agentkit/reference/authorization/verify-the-user.md) | `POST /api/v1/connected_accounts/user/verify` | Confirm that the user who approved access is the user your app meant. | `actions.verify_connected_account_user` | `actions.verifyConnectedAccountUser` |


## Get an authorization link

`POST /api/v1/connected_accounts/magic_link`

Creates a one-time authorization link that takes the user to the app's consent screen, or to a form for their API key, for one connection. If the user has no connected account for the connection yet, the call creates it first. When the user finishes, the account becomes `ACTIVE`. With user verification on, it becomes `PENDING_VERIFICATION` instead, and stays that way until you call [Verify the user](https://docs.scalekit.com/agentkit/reference/authorization/verify-the-user/). The link expires 5 minutes after you create it, so create a new one each time you send it. The endpoint path and the `connected_account.magic_link_generated` event call it a magic link.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `id` | string | No | Unique identifier for the connected account. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `organization_id` | string | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `state` | string | No | A value of your own, such as a session ID. Scalekit adds it to the request it sends to `user_verify_url`, so your app can check that the request is the one it started. |
| `user_id` | string | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |
| `user_verify_url` | string | No | Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `expiry` | string | When the link stops working: 5 minutes after you created it. |
| `link` | string | The authorization link to send the user to. It's on your environment's domain and works once. |

**Errors**

- `400`: Invalid request - missing required parameters, or a malformed connected account ID
- `401`: Authentication required - missing or invalid access token
- `404`: Not found - no connection with this name exists in the environment. Error code `RESOURCE_NOT_FOUND`.

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts/magic_link" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "gmail",
    "identifier": "user_123",
    "user_verify_url": "https://app.example.com/verify",
    "state": "[SESSION STATE]"
  }'
```

**Response**

```json
{
  "link": "https://your-env.scalekit.dev/magicLink/7f0c2b9e-4d1a-4c3e-9b8f-2a6d5e1c3f40_o",
  "expiry": "2026-10-02T14:35:00Z"
}
```

**Python SDK:** `scalekit_client.actions.get_authorization_link`

Creates the link a user opens to connect their account.

```python
scalekit_client.actions.get_authorization_link(
    identifier: Optional[str] = None,
    connection_name: Optional[str] = None,
    connected_account_id: Optional[str] = None,
    state: Optional[str] = None,
    user_verify_url: Optional[str] = None,
) -> MagicLinkResponse
```

Example:

```python
result = scalekit_client.actions.get_authorization_link(
    identifier="user_123",
    connection_name="gmail",
    state="[SESSION STATE]",
    user_verify_url="https://app.example.com/verify",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connection_name` | `Optional[str]` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_account_id` | `Optional[str]` | No | Connected account ID |
| `state` | `Optional[str]` | No | A value of your own, such as a session ID. Scalekit adds it to the request it sends to `user_verify_url`, so your app can check that the request is the one it started. |
| `user_verify_url` | `Optional[str]` | No | Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier. |

Returns `MagicLinkResponse`: The authorization `link` and its `expiry`.

**Node.js SDK:** `scalekit.actions.getAuthorizationLink`

Creates the link a user opens to connect their account.

```ts
scalekit.actions.getAuthorizationLink(
  params: {
    connectionName?: string;
    identifier?: string;
    connectedAccountId?: string;
    organizationId?: string;
    userId?: string;
    state?: string;
    userVerifyUrl?: string;
  },
): Promise<GetMagicLinkForConnectedAccountResponse>
```

Example:

```ts
const result = await scalekit.actions.getAuthorizationLink({
  connectionName: "gmail",
  identifier: "user_123",
  state: "[SESSION STATE]",
  userVerifyUrl: "https://app.example.com/verify",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connectedAccountId` | `string` | No | Unique identifier for the connected account |
| `organizationId` | `string` | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `userId` | `string` | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |
| `state` | `string` | No | A value of your own, such as a session ID. Scalekit adds it to the request it sends to `user_verify_url`, so your app can check that the request is the one it started. |
| `userVerifyUrl` | `string` | No | Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier. |

Returns `Promise<GetMagicLinkForConnectedAccountResponse>`.

**Used in**

- [Apify Actor with per-user OAuth via Scalekit](https://docs.scalekit.com/cookbooks/apify-actor-per-user-oauth/)
- [Authorize a user](https://docs.scalekit.com/agentkit/tools/authorize/)
- [Build a daily briefing agent with Vercel AI SDK and Scalekit AgentKit](https://docs.scalekit.com/cookbooks/daily-briefing-agent/)
- [Build a Mastra agent with Scalekit AgentKit tools](https://docs.scalekit.com/cookbooks/mastra-agentkit/)
- [Build a multi-agent email triage crew with CrewAI](https://docs.scalekit.com/cookbooks/crewai-agentkit-email-triage/)
- [Build a multi-user GitHub PR summarizer agent](https://docs.scalekit.com/cookbooks/render-github-pr-summarizer/)
- [Build an agent that books meetings and drafts emails](https://docs.scalekit.com/cookbooks/schedule-meeting-and-draft-email/)
- [Claude Managed Agents](https://docs.scalekit.com/agentkit/examples/claude-managed-agents/)
- [FastRouter + Scalekit tool calling](https://docs.scalekit.com/cookbooks/fastrouter-agentkit-tool-calling/)
- [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/)
- [Migrate from Composio to Scalekit](https://docs.scalekit.com/agentkit/advanced/migrate-from-composio/)
- [Quickstart](https://docs.scalekit.com/agentkit/quickstart/)
- [Trace AgentKit tool calls in LangSmith](https://docs.scalekit.com/cookbooks/langsmith-tracing-agentkit/)
- [Troubleshoot connection and OAuth errors](https://docs.scalekit.com/agentkit/troubleshooting/)
- [Verify users](https://docs.scalekit.com/agentkit/user-verification/)

## Verify the user

`POST /api/v1/connected_accounts/user/verify`

Confirms that the user who just authorized a connection is the user your app meant, then makes their connected account `ACTIVE`. When your environment verifies users with a custom verifier, Scalekit sends the user to your `user_verify_url` after they approve access, with an `auth_request_id` query parameter. Call this endpoint from your server with that `auth_request_id` and the identifier of the user signed in to your app, then send the user to `post_user_verify_redirect_url`. If the identifier doesn't match the one the [authorization link](https://docs.scalekit.com/agentkit/reference/authorization/get-an-authorization-link/) was created for, the call returns `403` and the account stays `PENDING_VERIFICATION`.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `auth_request_id` | string | Yes | The `auth_request_id` query parameter from the request Scalekit sent to your `user_verify_url`. Pass it as it is. |
| `identifier` | string | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `post_user_verify_redirect_url` | string | Where to send the user next, to finish connecting. |

**Errors**

- `400`: Invalid request - missing or malformed fields
- `401`: Unauthorized - invalid or missing access token
- `403`: Forbidden - identifier mismatch
- `404`: Not found - no pending flow for the given auth_request_id or already consumed

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts/user/verify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_request_id": "[AUTH REQUEST ID]",
    "identifier": "user_123"
  }'
```

**Response**

```json
{
  "post_user_verify_redirect_url": "https://env1.example.com/connect/success"
}
```

**Python SDK:** `scalekit_client.actions.verify_connected_account_user`

Confirms the user who authorized is the user your app meant.

```python
scalekit_client.actions.verify_connected_account_user(
    auth_request_id: str,
    identifier: str,
) -> VerifyConnectedAccountUserResponse
```

Example:

```python
result = scalekit_client.actions.verify_connected_account_user(
    auth_request_id="[AUTH REQUEST ID]",
    identifier="user_123",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `auth_request_id` | `str` | Yes | The `auth_request_id` query parameter from the request Scalekit sent to your `user_verify_url`. Pass it as it is. |
| `identifier` | `str` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |

Returns `VerifyConnectedAccountUserResponse`: The `post_user_verify_redirect_url` to send the user to.

**Node.js SDK:** `scalekit.actions.verifyConnectedAccountUser`

Confirms the user who authorized is the user your app meant. Call it from your server when Scalekit sends the user to your `userVerifyUrl`, with the `authRequestId` from that request and the identifier of the user signed in to your app. The connected account becomes `ACTIVE`.

```ts
scalekit.actions.verifyConnectedAccountUser(
  params: {
    authRequestId: string;
    identifier: string;
  },
): Promise<VerifyConnectedAccountUserResponse>
```

Example:

```ts
const result = await scalekit.actions.verifyConnectedAccountUser({
  authRequestId: "[AUTH REQUEST ID]",
  identifier: "user_123",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `authRequestId` | `string` | Yes | The `auth_request_id` query parameter from the request Scalekit sent to your `user_verify_url`. Pass it as it is. |
| `identifier` | `string` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |

Returns `Promise<VerifyConnectedAccountUserResponse>`.

**Used in**

- [Build a multi-user GitHub PR summarizer agent](https://docs.scalekit.com/cookbooks/render-github-pr-summarizer/)
- [FastRouter + Scalekit tool calling](https://docs.scalekit.com/cookbooks/fastrouter-agentkit-tool-calling/)
- [Verify users](https://docs.scalekit.com/agentkit/user-verification/)


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |