<!-- llms.txt: https://workos.com/llms.txt -->

# AuthKit

AuthKit is a user management platform that provides a set of user authentication and organization security features designed to provide a fast, scalable integration while handling all of the user management complexity that comes with advanced B2B customer needs.

To automatically respond to AuthKit activities, like authentication and changes related to the users, use the corresponding [events](https://workos.com/docs/events).

## Create a CORS origin

Creates a new CORS origin for the API key's application. CORS origins allow browser-based applications to make requests to the WorkOS API.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/user_management/cors_origins" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "origin": "https://example.com"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.create_cors_origin(origin: "https://example.com")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.create_cors_origin(origin="https://example.com")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().CreateCORSOrigin(context.Background(), &workos.UserManagementCreateCORSOriginParams{
		Origin: "https://example.com",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->userManagement()->createCorsOrigin(origin: "https://example.com");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.CreateCorsOriginOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateCorsOriginOptions options =
    CreateCorsOriginOptions.builder().origin("https://example.com").build();

workos.userManagement.createCorsOrigin(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.CreateCorsOriginAsync(new UserManagementCreateCorsOriginOptions {
    Origin = "https://example.com",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::user_management::CreateCorsOriginParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .create_cors_origin(
            CreateCorsOriginParams {
                origin: "https://example.com".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "cors_origin",
  "id": "cors_origin_01HXYZ123456789ABCDEFGHIJ",
  "origin": "https://example.com",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Import a connected account

Imports a [connected account](https://workos.com/docs/reference/pipes/connected-account) for a user by providing OAuth tokens directly. Use this to migrate existing connections or set up connections without going through the OAuth flow.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/user_management/users/user_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789" \
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.create_user_connected_account(
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.create_user_connected_account(
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().CreateUserConnectedAccount(context.Background(), "user_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->createUserConnectedAccount(
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.pipes.createUserConnectedAccount("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.CreateUserConnectedAccountAsync("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .pipes()
        .create_user_connected_account(
            "user_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": null,
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "state": "connected",
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Get Radar Challenge details

Get the details of an existing Radar Challenge, including the OTP code.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/user_management/radar_challenges/radar_challenge_01HWZBQZY2M3AMQW166Q22K88F" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.get_radar_challenge(id: "radar_challenge_01HWZBQZY2M3AMQW166Q22K88F")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.get_radar_challenge(
    id_="radar_challenge_01HWZBQZY2M3AMQW166Q22K88F"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().GetRadarChallenge(context.Background(), "radar_challenge_01HWZBQZY2M3AMQW166Q22K88F")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->userManagement()
    ->getRadarChallenge(id: "radar_challenge_01HWZBQZY2M3AMQW166Q22K88F");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.userManagement.getRadarChallenge("radar_challenge_01HWZBQZY2M3AMQW166Q22K88F");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.GetRadarChallengeAsync("radar_challenge_01HWZBQZY2M3AMQW166Q22K88F");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .get_radar_challenge("radar_challenge_01HWZBQZY2M3AMQW166Q22K88F")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "radar_challenge",
  "id": "radar_challenge_01HWZBQZY2M3AMQW166Q22K88F",
  "type": "email",
  "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "email": "marcelina.davis@example.com",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "code": "123456"
}
```

:::

## List CORS origins

Lists the CORS origins for the current environment.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/user_management/cors_origins" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.list_cors_origins
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.list_cors_origins()
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().ListCORSOrigins(context.Background())
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->userManagement()->listCorsOrigins();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.userManagement.listCorsOrigins();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.ListCorsOriginsAsync();
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .list_cors_origins()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "cors_origin",
      "id": "cors_origin_01HXYZ123456789ABCDEFGHIJ",
      "origin": "https://example.com",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "cors_origin_01HXYZ123456789ABCDEFGHIJ",
    "after": "cors_origin_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

## Send a Radar SMS challenge

Sends a one-time verification code over SMS to a user as part of a Radar challenge. Use the returned `verification_id` to authenticate the user with the `urn:workos:oauth:grant-type:radar-sms-challenge:code` grant type.

> **Note:** Radar in the User Management APIs is currently in preview, [contact us](mailto:support@workos.com) to request access.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/user_management/radar_challenges" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
        "pending_authentication_token": "cTDQJTTkTkkVYxbn...",
        "phone_number": "+15555550123"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.user_management.create_radar_challenge(
  user_id: "user_01E4ZCR3C56J083X43JQXF3JK5",
  pending_authentication_token: "cTDQJTTkTkkVYxbn...",
  phone_number: "+15555550123"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.user_management.create_radar_challenge(
    user_id="user_01E4ZCR3C56J083X43JQXF3JK5",
    pending_authentication_token="cTDQJTTkTkkVYxbn...",
    phone_number="+15555550123",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.UserManagement().CreateRadarChallenge(context.Background(), &workos.UserManagementCreateRadarChallengeParams{
		UserID:                     "user_01E4ZCR3C56J083X43JQXF3JK5",
		PendingAuthenticationToken: "cTDQJTTkTkkVYxbn...",
		PhoneNumber:                "+15555550123",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->userManagement()
    ->createRadarChallenge(
        userId: "user_01E4ZCR3C56J083X43JQXF3JK5",
        pendingAuthenticationToken: "cTDQJTTkTkkVYxbn...",
        phoneNumber: "+15555550123",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.CreateRadarChallengeOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateRadarChallengeOptions options =
    CreateRadarChallengeOptions.builder()
        .userId("user_01E4ZCR3C56J083X43JQXF3JK5")
        .pendingAuthenticationToken("cTDQJTTkTkkVYxbn...")
        .phoneNumber("+15555550123")
        .build();

workos.userManagement.createRadarChallenge(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.UserManagement.CreateRadarChallengeAsync(new UserManagementCreateRadarChallengeOptions {
    UserId = "user_01E4ZCR3C56J083X43JQXF3JK5",
    PendingAuthenticationToken = "cTDQJTTkTkkVYxbn...",
    PhoneNumber = "+15555550123",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::user_management::CreateRadarChallengeParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .user_management()
        .create_radar_challenge(
            CreateRadarChallengeParams {
                user_id: "user_01E4ZCR3C56J083X43JQXF3JK5".into(),
                pending_authentication_token: "cTDQJTTkTkkVYxbn...".into(),
                phone_number: "+15555550123".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "verification_id": "vrf_01HXYZ123456789ABCDEFGHIJ",
  "phone_number": "+15555550123"
}
```

:::

## Update a connected account

Updates a user's [connected account](https://workos.com/docs/reference/pipes/connected-account) tokens, scopes, or state for a specific provider.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/user_management/users/user_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
        "refresh_token": "ghr_xxxxxxxxxxxxxxxxxxxx",
        "expires_at": "2025-12-31T23:59:59.000Z",
        "scopes": [
            "repo",
            "user:email"
        ],
        "state": "connected"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.update_user_connected_account(
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.update_user_connected_account(
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().UpdateUserConnectedAccount(context.Background(), "user_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->updateUserConnectedAccount(
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.pipes.updateUserConnectedAccount("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.UpdateUserConnectedAccountAsync("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .pipes()
        .update_user_connected_account(
            "user_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": null,
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "state": "connected",
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

### POST /user_management/cors_origins

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `origin` | string | Yes | The origin URL to allow for CORS requests. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `cors_origin` | object | Distinguishes the CORS origin object. |

### POST /user_management/users/{user_id}/connected_accounts/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access_token` | string | No | The OAuth access token for the connected account. |
| `refresh_token` | string | No | The OAuth refresh token for the connected account. |
| `expires_at` | string | No | The ISO-8601 timestamp when the access token expires. Required when `access_token` is provided for tokens that expire. |
| `scopes` | string[] | No | The OAuth scopes granted for this connection. |
| `state` | "connected" \| "needs_reauthorization" | No | Explicitly set the state of the connected account. When omitted, the state is derived from the token combination provided. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter if the connection is scoped to an organization. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### GET /user_management/radar_challenges/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The unique ID of the Radar Challenge. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `radar_challenge` | object | Distinguishes the Radar Challenge object. |

### GET /user_management/cors_origins

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to `normal`. |

### POST /user_management/radar_challenges

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | The ID of the user to send the SMS challenge to. |
| `pending_authentication_token` | string | Yes | The pending authentication token from a previous authentication attempt that triggered the Radar challenge. |
| `phone_number` | string | Yes | The phone number to send the SMS verification code to. |
| `ip_address` | string | No | The IP address of the user's request. |
| `user_agent` | string | No | The user agent string from the user's request. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `verification_id` | string | The ID of the SMS verification. Pass this to the authenticate endpoint to verify the code. |
| `phone_number` | string | The phone number the verification code was sent to. |

### PUT /user_management/users/{user_id}/connected_accounts/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `access_token` | string | No | The OAuth access token for the connected account. |
| `refresh_token` | string | No | The OAuth refresh token for the connected account. |
| `expires_at` | string | No | The ISO-8601 timestamp when the access token expires. Required when `access_token` is provided for tokens that expire. |
| `scopes` | string[] | No | The OAuth scopes granted for this connection. |
| `state` | "connected" \| "needs_reauthorization" | No | Explicitly set the state of the connected account. When omitted, the state is derived from the token combination provided. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter if the connection is scoped to an organization. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |