User

Represents a user identity in your application. A user can sign up in your application directly with a method like password, or they can be JIT-provisioned through an organization’s SSO connection.

Users may belong to organizations as members.

See the events reference documentation for the user events.

Get a user

Get the details of an existing user.

cURL

 curl "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "user",
  "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "name": "Marcelina Davis",
  "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
  "email": "marcelina.davis@example.com",
  "email_verified": true,
  "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
  "metadata": {
    "timezone": "America/New_York"
  },
  "last_sign_in_at": "2025-06-25T19:07:33.155Z",
  "locale": "en-US",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/user_management/users/:id`

`Parameters`

`Returns`

Get a user by external ID

Get the details of an existing user by an external identifier.

cURL

 curl "https://api.workos.com/user_management/users/external_id/f1ffa2b2-c20b-4d39-be5c-212726e11222" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "user",
  "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "name": "Marcelina Davis",
  "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
  "email": "marcelina.davis@example.com",
  "email_verified": true,
  "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
  "metadata": {
    "timezone": "America/New_York"
  },
  "last_sign_in_at": "2025-06-25T19:07:33.155Z",
  "locale": "en-US",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/user_management/users/external_id/:external_id`

`Parameters`

`Returns`

List users

Get a list of all of your existing users matching the criteria specified.

cURL

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

 {
  "object": "list",
  "data": [
    {
      "object": "user",
      "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
      "first_name": "Marcelina",
      "last_name": "Davis",
      "name": "Marcelina Davis",
      "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
      "email": "marcelina.davis@example.com",
      "email_verified": true,
      "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
      "metadata": {
        "timezone": "America/New_York"
      },
      "last_sign_in_at": "2025-06-25T19:07:33.155Z",
      "locale": "en-US",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "user_01HXYZ123456789ABCDEFGHIJ",
    "after": "user_01HXYZ987654321KJIHGFEDCBA"
  }
}

GET

`/user_management/users`

`Parameters`

`Returns` `object`

Create a user

Create a new user in the current environment.

cURL

 curl --request POST \
  --url "https://api.workos.com/user_management/users" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "email": "marcelina.davis@example.com",
        "password": "i8uv6g34kd490s",
        "first_name": "Marcelina",
        "last_name": "Davis",
        "email_verified": false
    }
BODY

 {
  "object": "user",
  "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "name": "Marcelina Davis",
  "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
  "email": "marcelina.davis@example.com",
  "email_verified": true,
  "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
  "metadata": {
    "timezone": "America/New_York"
  },
  "last_sign_in_at": "2025-06-25T19:07:33.155Z",
  "locale": "en-US",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

POST

`/user_management/users`

`Returns`

Update a user

Updates properties of a user. The omitted properties will be left unchanged.

cURL

 curl --request PUT \
  --url "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "first_name": "Marcelina",
        "last_name": "Davis",
        "email_verified": true,
        "external_id": "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191",
        "metadata": {
            "timezone": "America/New_York"
        },
        "locale": "en-US"
    }
BODY

 {
  "object": "user",
  "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
  "first_name": "Marcelina",
  "last_name": "Davis",
  "name": "Marcelina Davis",
  "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
  "email": "marcelina.davis@example.com",
  "email_verified": true,
  "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
  "metadata": {
    "timezone": "America/New_York"
  },
  "last_sign_in_at": "2025-06-25T19:07:33.155Z",
  "locale": "en-US",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

PUT

`/user_management/users/:id`

`Parameters`

`Returns`

Delete a user

Permanently deletes a user in the current environment. It cannot be undone.

Request

cURL

 curl --request DELETE \
  --url https://api.workos.com/user_management/users/user_01F3GZ5ZGZBZVQGZVHJFVXZJGZ \
  --header "Authorization: Bearer sk_example_123456789"

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

const workos = new WorkOS('sk_example_123456789');

await workos.userManagement.deleteUser('user_01F3GZ5ZGZBZVQGZVHJFVXZJGZ');

 require "workos"

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

WorkOS.client.user_management.delete_user(id: "user_01E4ZCR3C56J083X43JQXF3JK5")

 from workos import WorkOSClient

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

client.user_management.delete_user(id_="user_01E4ZCR3C56J083X43JQXF3JK5")

 package main

import (
	"context"

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

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

	_, err := client.UserManagement().Delete(context.Background(), "user_01E4ZCR3C56J083X43JQXF3JK5")
	if err != nil {
		panic(err)
	}
}

 <?php

use WorkOS\WorkOS;

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

$workos->userManagement()->deleteUser(id: "user_01E4ZCR3C56J083X43JQXF3JK5");

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.userManagement.deleteUser("user_01E4ZCR3C56J083X43JQXF3JK5");

 using WorkOS;

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

await client.UserManagement.DeleteAsync("user_01E4ZCR3C56J083X43JQXF3JK5");

 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()
        .delete_user("user_01E4ZCR3C56J083X43JQXF3JK5")
        .await?;

    Ok(())
}

DELETE

`/user_management/users/:id`

`Parameters`

Verify email

Verifies an email address using the one-time code received by the user.

cURL

 curl --request POST \
  --url "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/email_verification/confirm" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "code": "123456"
    }
BODY

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "name": "Marcelina Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  }
}

POST

`/user_management/users/:id/email_verification/confirm`

`Parameters`

`Returns`

Send verification email

Sends an email that contains a one-time code used to verify a user’s email address.

cURL

 curl --request POST \
  --url "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/email_verification/send" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "name": "Marcelina Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  }
}

POST

`/user_management/users/:id/email_verification/send`

`Parameters`

`Returns`

List authorized applications

Get a list of all Connect applications that the user has authorized.

cURL

 curl "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/authorized_applications" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "object": "list",
  "data": [
    {
      "object": "authorized_connect_application",
      "id": "authorized_connect_app_01HXYZ123456789ABCDEFGHIJ",
      "granted_scopes": [
        "openid",
        "profile",
        "email"
      ],
      "oauth_resource": "https://api.example.com/resource",
      "application": {
        "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": "authorized_connect_app_01HXYZ123456789ABCDEFGHIJ",
    "after": "authorized_connect_app_01HXYZ987654321KJIHGFEDCBA"
  }
}

GET

`/user_management/users/:user_id/authorized_applications`

`Parameters`

`Returns` `object`

Delete an authorized application

Delete an existing Authorized Connect Application.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/authorized_applications/conn_app_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

DELETE

`/user_management/users/:user_id/authorized_applications/:application_id`

`Parameters`

`Returns`

Confirm email change

Confirms an email change using the one-time code received by the user.

cURL

 curl --request POST \
  --url "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/email_change/confirm" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "code": "123456"
    }
BODY

 {
  "object": "email_change_confirmation",
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "name": "Marcelina Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "new.email@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  }
}

POST

`/user_management/users/:id/email_change/confirm`

`Parameters`

`Returns`

Send email change code

Sends an email that contains a one-time code used to change a user’s email address.

cURL

 curl --request POST \
  --url "https://api.workos.com/user_management/users/user_01E4ZCR3C56J083X43JQXF3JK5/email_change/send" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "new_email": "new.email@example.com"
    }
BODY

 {
  "object": "email_change",
  "user": {
    "object": "user",
    "id": "user_01E4ZCR3C56J083X43JQXF3JK5",
    "first_name": "Marcelina",
    "last_name": "Davis",
    "name": "Marcelina Davis",
    "profile_picture_url": "https://workoscdn.com/images/v1/123abc",
    "email": "marcelina.davis@example.com",
    "email_verified": true,
    "external_id": "f1ffa2b2-c20b-4d39-be5c-212726e11222",
    "metadata": {
      "timezone": "America/New_York"
    },
    "last_sign_in_at": "2025-06-25T19:07:33.155Z",
    "locale": "en-US",
    "created_at": "2026-01-15T12:00:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "new_email": "new.email@example.com",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z"
}

Sends email

POST

`/user_management/users/:id/email_change/send`

`Parameters`

`Returns`

Identity Continue to the next section

Up next

User

Get a user

/user_management/users/:id

Parameters

id: string

Returns

user: object

Get a user by external ID

/user_management/users/external_id/:external_id

Parameters

external_id: string

Returns

user: object

List users

/user_management/users

Parameters

before?: string

after?: string

limit?: integer

order?: "normal" | "desc" | "asc"

organization?: string

organization_id?: string

email?: string

Returns object

object: "list"

data: object[]

list_metadata: object

Create a user

/user_management/users

email: string

first_name?: string

last_name?: string

name?: string

email_verified?: boolean

metadata?: object

external_id?: string

password?: string

password_hash?: string

password_hash_type?: "bcrypt" | "firebase-scrypt" | "ssha" | ..."bcrypt" | "firebase-scrypt" | "ssha" | "scrypt" | "pbkdf2" | "argon2"

Returns

user: object

Update a user

/user_management/users/:id

email?: string

first_name?: string

last_name?: string

name?: string

email_verified?: boolean

metadata?: object

external_id?: string

locale?: string

password?: string

password_hash?: string

password_hash_type?: "bcrypt" | "firebase-scrypt" | "ssha" | ..."bcrypt" | "firebase-scrypt" | "ssha" | "scrypt" | "pbkdf2" | "argon2"

Parameters

id: string

Returns

user: object

Delete a user

/user_management/users/:id

Parameters

id: string

Verify email

/user_management/users/:id/email_verification/confirm

code: string

Parameters

id: string

Returns

user: object

Send verification email

/user_management/users/:id/email_verification/send

Parameters

id: string

Returns

user: object

List authorized applications

/user_management/users/:user_id/authorized_applications

Parameters

user_id: string

before?: string

`/user_management/users/:id`

`Parameters`

`Returns`

`/user_management/users/external_id/:external_id`

`Parameters`

`Returns`

`/user_management/users`

`Parameters`

`Returns` `object`

`/user_management/users`

`Returns`

`/user_management/users/:id`

`Parameters`

`Returns`

`/user_management/users/:id`

`Parameters`

`/user_management/users/:id/email_verification/confirm`

`Parameters`

`Returns`

`/user_management/users/:id/email_verification/send`

`Parameters`

`Returns`

`/user_management/users/:user_id/authorized_applications`

`Parameters`

`Returns` `object`

`/user_management/users/:user_id/authorized_applications/:application_id`

`Parameters`

`Returns`

`/user_management/users/:id/email_change/confirm`

`Parameters`

`Returns`

`/user_management/users/:id/email_change/send`

`Parameters`

`Returns`