WorkOS API Reference

https://workos.com/docs/reference
Admin
The WorkOS API enables developers to add enterprise features like AuthKit, Single Sign-On, Directory...
Tokens:1,159,814
Snippets:5,852
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Get a Connection - Response Example

Source: https://workos.com/docs/reference/sso/connection/delete

Example response from the Get a Connection request. Shows the connection object with fields like id, organization_id, connection_type, name, state, domains, and timestamps.

```json
{
  "object": "connection",
  "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "connection_type": "OktaSAML",
  "name": "Foo Corp",
  "state": "active",
  "domains": [
    {
      "id": "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A",
      "object": "connection_domain",
      "domain": "foo-corp.com"
    }
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

--------------------------------

### Get agent instance session - Request examples (curl, Ruby, Python, Go, PHP, Java, .NET, Rust)

Source: https://workos.com/docs/reference/agents/session/get

Code examples for retrieving an agent instance session by ID using the WorkOS API. Each example uses the session ID 'agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY' and an API key 'sk_example_123456789'. The Ruby, Python, Go, PHP, Java, .NET, and Rust examples use the respective WorkOS SDKs.

```bash
curl "https://api.workos.com/agents/sessions/agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY" \
  --header "Authorization: Bearer sk_example_123456789"
```

```ruby
require "workos"

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

WorkOS.client.agents.get_session(agent_instance_session_id: "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```python
from workos import WorkOSClient

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

client.agents.get_session(
    agent_instance_session_id="agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY"
)
```

```go
package main

import (
	"context"

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

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

	_, err := client.Agents().GetSession(context.Background(), "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
	if err != nil {
		panic(err)
	}
}
```

```php
<?php

use WorkOS\WorkOS;

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

$workos
    ->agents()
    ->getSession(
        agentInstanceSessionId: "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
    );
```

```java
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.getSession("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```dotnet
using WorkOS;

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

await client.Agents.GetSessionAsync("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```rust
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
        .agents()
        .get_session("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
        .await?;

    Ok(())
}
```

--------------------------------

### Get a team - Request (.NET)

Source: https://workos.com/docs/reference/platform/team

.NET example using the WorkOS .NET SDK to get a team. Requires the 'WorkOS' package and both API key and client ID.

```dotnet
using WorkOS;

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

await client.PlatformTeams.GetTeamAsync("team_01JX9AN6E02HAG2Q2CKGC1XT5W");
```

--------------------------------

### Get a User Profile - Request (.NET)

Source: https://workos.com/docs/reference/sso/profile

.NET example using the WorkOS .NET SDK to get a user's profile. Requires an API key and client ID.

```cs
using WorkOS;

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

await client.SSO.GetProfileAsync();
```

--------------------------------

### List Connect Applications - Request Examples

Source: https://workos.com/docs/reference/workos-connect/applications/create

Requests to list all Connect Applications in the current environment. Each language example uses the WorkOS SDK or API with the required authentication credentials (API key and client ID where applicable).

```bash
curl "https://api.workos.com/connect/applications" \
  --header "Authorization: Bearer sk_example_123456789"
```

```ruby
require "workos"

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

WorkOS.client.connect.list_applications
```

```python
from workos import WorkOSClient

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

client.connect.list_applications()
```

```go
package main

import (
	"context"

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

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

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

```php
<?php

use WorkOS\WorkOS;

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

$workos->connect()->listApplications();
```

```java
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.connect.listApplications();
```

```dotnet
using WorkOS;

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

await client.Connect.ListApplicationsAsync();
```

```rust
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
        .connect()
        .list_applications()
        .await?;

    Ok(())
}
```

--------------------------------

### Get authorization URL - Request examples

Source: https://workos.com/docs/reference/pipes/connected-account/get-authorize-url

Request examples for the Get authorization URL endpoint across multiple SDKs. Each example calls the authorizeDataIntegration method with the GitHub slug and a user ID, returning an authorization URL. The curl example uses a POST request to the /data-integrations/github/authorize endpoint with a Bearer token.

```bash
curl --request POST \
  --url "https://api.workos.com/data-integrations/github/authorize" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT"
    }
BODY
```

```js
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const { url } = await workos.pipes.authorizeDataIntegration({
  slug: 'github',
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
});
```

```ruby
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
require "workos"

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

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

```python
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
from workos import WorkOSClient

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

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

```go
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
package main

import (
	"context"

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

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

	_, err := client.Pipes().AuthorizeDataIntegration(context.Background(), "github", &workos.PipesAuthorizeDataIntegrationParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
	})
	if err != nil {
		panic(err)
	}
}
```

```php
<?php
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions

use WorkOS\WorkOS;

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

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

```java
// workos:manual - preserve required legacy parameters until oagen supports
// optional-intent unions
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.AuthorizeDataIntegrationOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

AuthorizeDataIntegrationOptions options = AuthorizeDataIntegrationOptions.builder()
                                              .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
                                              .build();

workos.pipes.authorizeDataIntegration("github", options);
```

```dotnet
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
using WorkOS;

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

await client.Pipes.AuthorizeDataIntegrationAsync("github", new PipesAuthorizeDataIntegrationOptions {
    UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
});
```

```rust
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
use workos::Client;
use workos::pipes::AuthorizeDataIntegrationParams;

#[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()
        .authorize_data_integration(
            "github",
            AuthorizeDataIntegrationParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

--------------------------------

### List waitlists - Request examples (curl, Ruby, Python, Go, PHP, Java, .NET, Rust)

Source: https://workos.com/docs/reference/authkit/waitlist/deny

These are the request examples for listing waitlists. Each example uses the appropriate SDK or HTTP client for the language. The endpoint is not paginated, so list_metadata cursors are always null.

```bash
curl "https://api.workos.com/user_management/waitlists" \
  --header "Authorization: Bearer sk_example_123456789"
```

```ruby
require "workos"

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

WorkOS.client.user_management.list_waitlists
```

```python
from workos import WorkOSClient

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

client.user_management.list_waitlists()
```

```go
package main

import (
	"context"

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

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

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

```php
<?php

use WorkOS\WorkOS;

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

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

```java
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.userManagement.listWaitlists();
```

```dotnet
using WorkOS;

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

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

```rust
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_waitlists()
        .await?;

    Ok(())
}
```

--------------------------------

### Create a group - Request examples (curl, Ruby, Python, Go, PHP, Java, .NET, Rust)

Source: https://workos.com/docs/reference/groups/get

These are the request examples for creating a group. They are presented as tabs in the source. Each example uses the same API endpoint and parameters. The curl example uses a POST request to the /organizations/{organization_id}/groups endpoint with a JSON body. The other examples use the WorkOS SDK in their respective languages.

```bash
curl --request POST \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Engineering",
        "description": "The engineering team"
    }
BODY
```

```ruby
require "workos"

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

WorkOS.client.groups.create_organization_group(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  name: "Engineering"
)
```

```python
from workos import WorkOSClient

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

client.groups.create_organization_group(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY", name="Engineering"
)
```

```go
package main

import (
	"context"

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

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

	_, err := client.Groups().CreateOrganizationGroup(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", &workos.GroupsCreateOrganizationGroupParams{
		Name: "Engineering",
	})
	if err != nil {
		panic(err)
	}
}
```

```php
<?php

use WorkOS\WorkOS;

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

$workos
    ->groups()
    ->createOrganizationGroup(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        name: "Engineering",
    );
```

```java
import com.workos.WorkOS;
import com.workos.groups.GroupsApi.CreateOrganizationGroupOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateOrganizationGroupOptions options =
    CreateOrganizationGroupOptions.builder().name("Engineering").build();

workos.groups.createOrganizationGroup("org_01EHWNCE74X7JSDV0X3SZ3KJNY", options);
```

```dotnet
using WorkOS;

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

await client.Groups.CreateOrganizationGroupAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
                                                 new GroupsCreateOrganizationGroupOptions {
                                                     Name = "Engineering",
                                                 });
```

```rust
use workos::Client;
use workos::groups::CreateOrganizationGroupParams;

#[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
        .groups()
        .create_organization_group(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            CreateOrganizationGroupParams {
                name: "Engineering".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

--------------------------------

### GET /user_management/waitlists/{id}

Source: https://workos.com/docs/reference/authkit/waitlist

This snippet documents the GET endpoint for retrieving a waitlist by its ID, including the request and response examples.

```APIDOC
## GET /user_management/waitlists/{id}

### Description
Get the details of an existing waitlist.

### Method
GET

### Endpoint
`/user_management/waitlists/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the waitlist to retrieve.

### Request Example
```bash
curl "https://api.workos.com/user_management/waitlists/waitlist_01E4ZCR3C56J083X43JQXF3JK5" \
  --header "Authorization: Bearer sk_example_123456789"
```

### Response
#### Success Response (200)
- **object** (string) - The type of object returned, always "waitlist".
- **id** (string) - The unique identifier of the waitlist.
- **created_at** (string) - The timestamp when the waitlist was created.
- **updated_at** (string) - The timestamp when the waitlist was last updated.

#### Response Example
```json
{
  "object": "waitlist",
  "id": "waitlist_01E4ZCR3C56J083X43JQXF3JK5",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```
```

--------------------------------

### Create a redirect URI - Request examples in multiple languages

Source: https://workos.com/docs/reference/authkit/redirect-uri/list

Shows how to create a redirect URI using curl, Ruby, Python, Go, PHP, Java, .NET, and Rust. Each example uses the same API endpoint and parameters.

```bash
curl --request POST \
  --url "https://api.workos.com/user_management/redirect_uris" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "uri": "https://example.com/callback"
    }
BODY
```

```ruby
require "workos"

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

WorkOS.client.user_management.create_redirect_uri(uri: "https://example.com/callback")
```

```python
from workos import WorkOSClient

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

client.user_management.create_redirect_uri(uri="https://example.com/callback")
```

```go
package main

import (
	"context"

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

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

	_, err := client.UserManagement().CreateRedirectURI(context.Background(), &workos.UserManagementCreateRedirectURIParams{
		URI: "https://example.com/callback",
	})
	if err != nil {
		panic(err)
	}
}
```

```php
<?php

use WorkOS\WorkOS;

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

$workos
    ->userManagement()
    ->createRedirectUri(uri: "https://example.com/callback");
```

```java
import com.workos.WorkOS;
import com.workos.usermanagement.UserManagementApi.CreateRedirectUriOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateRedirectUriOptions options =
    CreateRedirectUriOptions.builder().uri("https://example.com/callback").build();

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

```dotnet
using WorkOS;

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

await client.UserManagement.CreateRedirectUriAsync(new UserManagementCreateRedirectUriOptions {
    Uri = "https://example.com/callback",
});
```

```rust
use workos::Client;
use workos::user_management::CreateRedirectUriParams;

#[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_redirect_uri(
            CreateRedirectUriParams {
                uri: "https://example.com/callback".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

--------------------------------

### GET /vault/v1/kv/{id}

Source: https://workos.com/docs/reference/vault/object/create

This snippet documents the HTTP GET endpoint for reading an object by its ID, including the request and response examples.

```APIDOC
## GET /vault/v1/kv/{id}

### Description
Fetch and decrypt an object by its unique identifier.

### Method
GET

### Endpoint
/vault/v1/kv/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the object to fetch.

### Request Example
```bash
curl "https://api.workos.com/vault/v1/kv/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: Bearer sk_example_123456789"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the object.
- **metadata** (object) - Metadata associated with the object.
  - **context** (object) - Context information.
    - **organization_id** (string) - The organization ID.
  - **environment_id** (string) - The environment ID.
  - **id** (string) - The object ID.
  - **key_id** (string) - The key ID used for encryption.
  - **updated_at** (string) - The timestamp of the last update.
  - **updated_by** (object) - Information about who updated the object.
    - **id** (string) - The ID of the updater.
    - **name** (string) - The name of the updater.
  - **version_id** (string) - The version ID.
- **name** (string) - The name of the object.
- **value** (string) - The decrypted value of the object.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "context": {
      "organization_id": "org_01K8ZYT4AWJ6XP0E0S8CTBHE3P"
    },
    "environment_id": "environment_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key_id": "bf65e326-43a0-4b20-88c4-07ff3de5434c",
    "updated_at": "2024-06-15T10:30:00Z",
    "updated_by": {
      "id": "key_01K8ZYT4AWJ6XP0E0S8CTBHE3P",
      "name": "My API Key"
    },
    "version_id": "c3d4e5f6-7890-abcd-ef12-34567890abcd"
  },
  "name": "my-secret",
  "value": "s3cr3t-v4lu3"
}
```
```

--------------------------------

### List Connect Applications - Response Example

Source: https://workos.com/docs/reference/workos-connect/applications/create

Example response from the List Connect Applications endpoint. Shows the list object structure, a Connect Application object with fields like application_type, redirect_uris, uses_pkce, and list_metadata for pagination.

```json
{
  "object": "list",
  "data": [
    {
      "application_type": "oauth",
      "redirect_uris": [
        {
          "uri": "https://example.com/callback",
          "default": true
        }
      ],
      "uses_pkce": true,
      "is_first_party": true,
      "object": "connect_application",
      "id": "conn_app_01HXYZ123456789ABCDEFGHIJ",
      "client_id": "client_01HXYZ123456789ABCDEFGHIJ",
      "description": "An application for managing user access",
      "name": "My Application",
      "scopes": [
        "openid",
        "profile",
        "email"
      ],
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "conn_app_01HXYZ123456789ABCDEFGHIJ",
    "after": "conn_app_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

--------------------------------

### Get a Directory User

Source: https://workos.com/docs/reference/directory-sync/directory-user/list

This snippet documents the GET endpoint to retrieve a directory user by its ID, including the request and response examples.

```APIDOC
## GET /directory_users/:id

### Description
Get the details of an existing Directory User.

### Method
GET

### Endpoint
`/directory_users/:id`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the directory user.

### Request Example
```bash
curl "https://api.workos.com/directory_users/directory_user_01E1JG7J09H96KYP8HM9B0G5SJ" \
  --header "Authorization: Bearer sk_example_123456789"
```

### Response
#### Success Response (200)
- **object** (string) - The type of object, always `directory_user`.
- **id** (string) - The unique identifier of the directory user.
- **directory_id** (string) - The unique identifier of the directory.
- **organization_id** (string) - The unique identifier of the organization.
- **idp_id** (string) - The identifier of the user in the identity provider.
- **email** (string) - The email address of the user.
- **first_name** (string) - The first name of the user.
- **last_name** (string) - The last name of the user.
- **name** (string) - The full name of the user.
- **state** (string) - The state of the user (e.g., `active`).
- **custom_attributes** (object) - Custom attributes associated with the user.
- **role** (object) - The primary role of the user.
- **roles** (array) - List of roles assigned to the user.
- **created_at** (string) - The timestamp when the user was created.
- **updated_at** (string) - The timestamp when the user was last updated.

#### Response Example
```json
{
  "object": "directory_user",
  "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "idp_id": "2836",
  "email": "marcelina.davis@example.com",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "name": "Marcelina Davis",
  "state": "active",
  "custom_attributes": {
    "department": "Engineering",
    "job_title": "Software Engineer"
  },
  "role": {
    "slug": "admin"
  },
  "roles": [
    {
      "slug": "admin"
    }
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```
```

--------------------------------

### Go (workos.Clent - Authorization().ListPermissions)

Source: https://workos.com/docs/reference/roles/permission/get

Creates a WorkOS Go client with an API key and lists permissions inside a main function while ignoring errors other than printing them via panic on failure.

```go
package main

import (
	"context"
	"github.com/WorkOS/workos-go/v10"
)

func main() {
	c := workos.NewClient("sk_example_123456789")
	_, err := c.Authorization().ListPermissions(context.Background())
	if err != named { panic(err) }
}
```

--------------------------------

### Get Export Response JSON

Source: https://workos.com/docs/reference/audit-logs/create-export

Example response from the Get Export endpoint. The URL expires after 10 minutes; refetching regenerates it.

```JSON
{
  "object": "audit_log_export",
  "id": "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V",
  "state": "ready",
  "url": "https://exports.audit-logs.com/audit-log-exports/export.csv",
  "created_at": "2022-09-02T17:14:57.094Z",
  "updated_at": "2022-09-02T17:14:57.094Z"
}
```

--------------------------------

### Get a User Profile - Response Example

Source: https://workos.com/docs/reference/sso/profile/get-user-profile

Example JSON response from the Get a User Profile endpoint. Shows the Profile object fields including id, organization_id, connection_id, connection_type, idp_id, email, name, role, roles, groups, custom_attributes, and raw_attributes.

```json
{
  "object": "profile",
  "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
  "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3",
  "connection_id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
  "connection_type": "OktaSAML",
  "idp_id": "103456789012345678901",
  "email": "todd@example.com",
  "first_name": "Todd",
  "last_name": "Rundgren",
  "name": "Todd Rundgren",
  "role": {
    "slug": "admin"
  },
  "roles": [
    {
      "slug": "admin"
    }
  ],
  "groups": [
    "Engineering",
    "Admins"
  ],
  "custom_attributes": {},
  "raw_attributes": {}
}
```

--------------------------------

### Get a resource - Request examples (curl, JS, Ruby, Python, Go, PHP, Java, .NET, Rust)

Source: https://workos.com/docs/reference/fga/resource/get

Use these requests to retrieve an authorization resource by its ID. Each example uses the resource ID 'authz_resource_01HXYZ123456789ABCDEFGHIJ' and an API key. The response is a JSON object with resource details.

```bash
curl "https://api.workos.com/authorization/resources/authz_resource_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const resource = await workos.authorization.getResource(
  'authz_resource_01HXYZ123456789ABCDEFGH',
);
```

```ruby
require "workos"

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

WorkOS.client.authorization.get_resource(resource_id: "authz_resource_01HXYZ123456789ABCDEFGHIJ")
```

```python
from workos import WorkOSClient

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

client.authorization.get_resource(
    resource_id="authz_resource_01HXYZ123456789ABCDEFGHIJ"
)
```

```go
package main

import (
	"context"

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

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

	_, err := client.Authorization().GetResource(context.Background(), "authz_resource_01HXYZ123456789ABCDEFGHIJ")
	if err != nil {
		panic(err)
	}
}
```

```php
<?php

use WorkOS\WorkOS;

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

$workos
    ->authorization()
    ->getResource(resourceId: "authz_resource_01HXYZ123456789ABCDEFGHIJ");
```

```java
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.getResource("authz_resource_01HXYZ123456789ABCDEFGHIJ");
```

```dotnet
using WorkOS;

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

await client.Authorization.GetResourceAsync("authz_resource_01HXYZ123456789ABCDEFGHIJ");
```

```rust
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
        .authorization()
        .get_resource("authz_resource_01HXYZ123456789ABCDEFGHIJ")
        .await?;

    Ok(())
}
```

--------------------------------

### GET /sso/authorize

Source: https://workos.com/docs/reference/sso/get-authorization-url

This snippet documents the GET /sso/authorize endpoint, including its query parameters, request example, response format, and error handling.

```APIDOC
## GET /sso/authorize

### Description
Generates an OAuth 2.0 authorization URL to authenticate a user with SSO. The generated URL automatically directs the user to their identity provider. Once the user authenticates with their identity provider, WorkOS issues a redirect to your redirect URI to complete the sign-in flow.

### Method
GET

### Endpoint
https://api.workos.com/sso/authorize

### Parameters
#### Query Parameters
- **response_type** (string) - Required - Must be set to `code`.
- **client_id** (string) - Required - Your WorkOS client ID.
- **redirect_uri** (string) - Required - The URI to redirect to after authentication.
- **state** (string) - Optional - A state value to include in the redirect URI.
- **connection** (string) - Optional - The connection ID. Mutually exclusive with `organization` and `provider`; exactly one must be provided.
- **organization** (string) - Optional - The organization ID. Mutually exclusive with `connection` and `provider`; exactly one must be provided.
- **provider** (string) - Optional - The OAuth provider. Mutually exclusive with `connection` and `organization`; exactly one must be provided.

### Request Example
```
curl "https://api.workos.com/sso/authorize" \
  -G \
  -d response_type=code \
  -d client_id=client_01HZBC6N1EB1ZY7KG32X \
  -d redirect_uri=https://your-app.com/callback \
  -d state=dj1kUXc0dzlXZ1hjUQ== \
  -d connection=conn_01E4ZCR3C56J083X43JQXF3JK5
```

### Response
#### Success Response (200)
Returns the authorization URL as a string.

#### Response Example
```
https://api.workos.com/sso/authorize?
response_type=code&
client_id=client_123456789&
redirect_uri=https://your-app.com/callback&
state=dj1kUXc0dzlXZ1hjUQ==&
connection=conn_01E4ZCR3C56J083X43JQXF3JK5
```

### Error Handling
If there is an issue generating an authorization URL, the API will return the original redirect URI with `error` and `error_description` query parameters. If provided, the `state` value will also be included.

#### Error Response Example
```
https://your-app.com/callback?error=organization_invalid&error_description=No%20connection%20associated%20with%20organization&state=123456789
```

Possible error codes and their descriptions are listed below.

| Error code | Description |
|------------|-------------|
| organization_invalid | No connection associated with organization |
```

--------------------------------

### List Directory Users - Request Examples

Source: https://workos.com/docs/reference/directory-sync/directory-user/get

Request examples for listing directory users across multiple languages. Each uses an API key and calls the directory sync list users method. The Node.js example includes a directory filter; others omit it.

```curl
curl "https://api.workos.com/directory_users" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const users = await workos.directorySync.listUsers({
  directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74',
});

console.log(users.data);
```

```ruby
require "workos"

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

WorkOS.client.directory_sync.list_users
```

```python
from workos import WorkOSClient

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

client.directory_sync.list_users()
```

```go
package main

import (
	"context"

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

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

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

```php
<?php

use WorkOS\WorkOS;

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

$workos->directorySync()->listUsers();
```

```java
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.listUsers();
```

```dotnet
using WorkOS;

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

await client.DirectorySync.ListUsersAsync();
```

```rust
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
        .directory_sync()
        .list_users()
        .await?;

    Ok(())
}
```

--------------------------------

### Get JWKS URL - Go

Source: https://workos.com/docs/reference/authkit/session-tokens

Go example using the WorkOS SDK to get the JWKS URL. Requires setting the API key.

```go
package main

import (
	"github.com/workos/workos-go/v2/pkg/usermanagement"
)

func main() {
	usermanagement.SetAPIKey(
		"sk_example_123456789",
	)

	jwksUrl, err := usermanagement.GetJWKSURL("client_123456789")
}
```

--------------------------------

### Get Factor - JSON Response

Source: https://workos.com/docs/reference/mfa/factor/enroll

Example JSON response for a successful Get Factor request, showing the authentication factor object with type 'totp'.

```json
{
  "object": "authentication_factor",
  "id": "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ",
  "type": "totp",
  "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "totp": {
    "issuer": "WorkOS",
    "user": "user@example.com"
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```
Tokens:
Raw