Retrieve a user | Clerk API (unofficial showcase)

1 parameter

user_idstringrequired

The unique identifier of the user to retrieve.

4 status codes

200Returns the user object with account details, including identifiers, profile information, contact methods, and authentication settings.

idstringrequired

objectstringrequired

String representing the object's type. Objects of the same type share the same value.

Allowed:user

external_idstringrequired

primary_email_address_idstringrequired

primary_phone_number_idstringrequired

primary_web3_wallet_idstringrequired

usernamestringrequired

first_namestringrequired

last_namestringrequired

localestringoptional

timezonestringoptional

profile_image_urlstringdeprecatedoptional

image_urlstringoptional

has_imagebooleanrequired

public_metadataobjectrequired

private_metadataobjectoptional

unsafe_metadataobjectoptional

email_addressesarray<object>required

phone_numbersarray<object>required

web3_walletsarray<object>required

passkeysarray<object>required

password_enabledbooleanrequired

two_factor_enabledbooleanrequired

totp_enabledbooleanrequired

backup_code_enabledbooleanrequired

mfa_enabled_atintegerrequired

Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.

mfa_disabled_atintegerrequired

Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.

password_last_updated_atintegeroptional

Unix timestamp of when the user's password was last updated.

external_accountsarray<object>required

saml_accountsarray<object>required

enterprise_accountsarray<object>required

organization_membershipsarray<object>optional

last_sign_in_atintegerrequired

Unix timestamp of last sign-in.

bannedbooleanrequired

Flag to denote whether user is banned or not.

lockedbooleanrequired

Flag to denote whether user is currently locked, i.e. restricted from signing in or not.

deprovisionedbooleanoptional

Flag to denote whether user has been deprovisioned and is restricted from signing in.

lockout_expires_in_secondsintegerrequired

The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.

verification_attempts_remainingintegerrequired

The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.

updated_atintegerrequired

Unix timestamp of last update.

created_atintegerrequired

Unix timestamp of creation.

delete_self_enabledbooleanrequired

If enabled, user can delete themselves via FAPI.

create_organization_enabledbooleanrequired

If enabled, user can create organizations via FAPI.

create_organizations_limitintegeroptional

The maximum number of organizations the user can create. 0 means unlimited.

last_active_atintegerrequired

Unix timestamp of the latest session activity, with day precision.

legal_accepted_atintegerrequired

Unix timestamp of when the user accepted the legal requirements.

bypass_client_trustbooleanoptional

When set to `true`, the user will bypass Device Trust checks during sign-in.

Default:false

directoriesarray<object>optional

All loaded directory links. Omitted when links were not loaded; an empty array means the user has no directory links.

directoryobjectdeprecatedoptional

The most recently updated directory link. Use directories for all links.

scimobjectdeprecatedoptional

Alias of directory. Use directories for all links.

400Returned when the request is unsuccessful.

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

401Returned when authentication is invalid.

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

404Returned when the user resource is not found.

errorsarray<object>required

metaobjectoptional

clerk_trace_idstringoptional

Error handling

A 400 is returned when the request is unsuccessful. A 401 is returned when authentication is invalid, and a 404 is returned when the user resource is not found. The user_id path parameter must identify the user to retrieve.

import { Client } from "@octridev/clerk";

const client = new Client({
  baseUrl: "https://api.clerk.com/v1",
  auth: { bearer: process.env.API_TOKEN },
});

const result = await client.users.get({ userId: "c0a80123-4567-89ab-cdef-0123456789ab" });

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "user",
  "external_id": "550e8400-e29b-41d4-a716-446655440000",
  "primary_email_address_id": "550e8400-e29b-41d4-a716-446655440000",
  "primary_phone_number_id": "550e8400-e29b-41d4-a716-446655440000",
  "primary_web3_wallet_id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "janedoe",
  "first_name": "Example Name",
  "last_name": "Example Name",
  "locale": "example_value",
  "timezone": "2026-01-15T09:00:00Z",
  "profile_image_url": "https://example.com",
  "image_url": "https://example.com",
  "has_image": true,
  "email_addresses": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "email_address",
      "email_address": "user@example.com",
      "reserved": true,
      "verification": {
        "object": "verification_otp",
        "status": "unverified",
        "strategy": "phone_code",
        "attempts": 1,
        "expire_at": 1,
        "channel": "example_value",
        "verified_at_client": "example_value"
      },
      "linked_to": [
        {
          "type": "standard",
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "matches_sso_connection": true,
      "created_at": 1,
      "updated_at": "2026-01-15T09:00:00Z"
    }
  ],
  "phone_numbers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "phone_number",
      "phone_number": "+44 7700 900123",
      "reserved_for_second_factor": true,
      "default_second_factor": true,
      "reserved": true,
      "verification": {
        "object": "verification_otp",
        "status": "unverified",
        "strategy": "phone_code",
        "attempts": 1,
        "expire_at": 1,
        "channel": "example_value",
        "verified_at_client": "example_value"
      },
      "linked_to": [
        {
          "type": "standard",
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "backup_codes": [
        "example_value"
      ],
      "created_at": 1,
      "updated_at": "2026-01-15T09:00:00Z"
    }
  ],
  "web3_wallets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "web3_wallet",
      "web3_wallet": "example_value",
      "verification": {
        "object": "verification_web3",
        "status": "unverified",
        "strategy": "web3_metamask_signature",
        "nonce": "example_value",
        "message": "This is an example message.",
        "attempts": 1,
        "expire_at": 1,
        "verified_at_client": "example_value"
      },
      "created_at": 1,
      "updated_at": "2026-01-15T09:00:00Z"
    }
  ],
  "passkeys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "passkey",
      "name": "Example Name",
      "last_used_at": 1,
      "verification": {
        "object": "verification_passkey",
        "status": "verified",
        "strategy": "passkey",
        "nonce": "nonce",
        "message": "This is an example message.",
        "attempts": 1,
        "expire_at": 1,
        "verified_at_client": "example_value"
      }
    }
  ],
  "password_enabled": true,
  "two_factor_enabled": true,
  "totp_enabled": true,
  "backup_code_enabled": true,
  "mfa_enabled_at": 1,
  "mfa_disabled_at": 1,
  "password_last_updated_at": "2026-01-15T09:00:00Z",
  "external_accounts": [
    {
      "object": "external_account",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "provider": "Example Academy Trust",
      "identification_id": "550e8400-e29b-41d4-a716-446655440000",
      "provider_user_id": "550e8400-e29b-41d4-a716-446655440000",
      "approved_scopes": "example_value",
      "email_address": "user@example.com",
      "email_address_verified": true,
      "first_name": "Example Name",
      "last_name": "Example Name",
      "avatar_url": "https://example.com",
      "image_url": "https://example.com",
      "username": "janedoe",
      "phone_number": "+44 7700 900123",
      "label": "example_value",
      "created_at": 1,
      "updated_at": "2026-01-15T09:00:00Z",
      "verification": {
        "object": "verification_oauth",
        "status": "unverified",
        "strategy": "example_value",
        "external_verification_redirect_url": "https://example.com",
        "error": {
          "message": null,
          "long_message": null,
          "code": null,
          "meta": null
        },
        "expire_at": 1,
        "attempts": 1,
        "verified_at_client": "example_value"
      }
    }
  ],
  "saml_accounts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "saml_account",
      "provider": "Example Academy Trust",
      "active": true,
      "email_address": "user@example.com",
      "first_name": "Example Name",
      "last_name": "Example Name",
      "provider_user_id": "550e8400-e29b-41d4-a716-446655440000",
      "last_authenticated_at": 1,
      "verification": {
        "object": "verification_saml",
        "status": "unverified",
        "strategy": "saml",
        "external_verification_redirect_url": "https://example.com",
        "error": {
          "message": null,
          "long_message": null,
          "code": null,
          "meta": null
        },
        "expire_at": 1,
        "attempts": 1,
        "verified_at_client": "example_value"
      },
      "saml_connection": "example_value"
    }
  ],
  "enterprise_accounts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "enterprise_account",
      "protocol": "oauth",
      "provider": "Example Academy Trust",
      "active": true,
      "email_address": "user@example.com",
      "first_name": "Example Name",
      "last_name": "Example Name",
      "provider_user_id": "550e8400-e29b-41d4-a716-446655440000",
      "enterprise_connection_id": "550e8400-e29b-41d4-a716-446655440000",
      "verification": {
        "object": "verification_ticket",
        "status": "unverified",
        "strategy": "ticket",
        "attempts": 1,
        "expire_at": 1,
        "verified_at_client": "example_value"
      },
      "enterprise_connection": "example_value",
      "last_authenticated_at": 1
    }
  ],
  "organization_memberships": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "object": "organization_membership",
      "role": "administrator",
      "role_name": "Example Name",
      "permissions": [
        "example_value"
      ],
      "organization": {
        "object": "organization",
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example Name",
        "slug": "my-example-resource",
        "image_url": "https://example.com",
        "has_image": true,
        "members_count": 42,
        "missing_member_with_elevated_permissions": true,
        "pending_invitations_count": 42,
        "max_allowed_memberships": 1,
        "admin_delete_enabled": true,
        "self_serve_sso_enabled": true,
        "self_serve_directory_sync_enabled": true,
        "created_by": "example_value",
        "created_at": 1,
        "updated_at": "2026-01-15T09:00:00Z",
        "last_active_at": 1,
        "role_set_key": "example_key_abc123"
      },
      "public_user_data": {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "Example Name",
        "last_name": "Example Name",
        "profile_image_url": "https://example.com",
        "image_url": "https://example.com",
        "has_image": true,
        "identifier": "example_value",
        "username": "janedoe",
        "banned": true,
        "deprovisioned": true
      },
      "created_at": 1,
      "updated_at": "2026-01-15T09:00:00Z"
    }
  ],
  "last_sign_in_at": 1,
  "banned": true,
  "locked": true,
  "deprovisioned": true,
  "lockout_expires_in_seconds": 1,
  "verification_attempts_remaining": 1,
  "updated_at": "2026-01-15T09:00:00Z",
  "created_at": 1,
  "delete_self_enabled": true,
  "create_organization_enabled": true,
  "create_organizations_limit": 1,
  "last_active_at": 1700690400000,
  "legal_accepted_at": 1700690400000,
  "bypass_client_trust": false,
  "directories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "directory_name": "Example Name",
      "provider": "Example Academy Trust",
      "enterprise_connection_id": "550e8400-e29b-41d4-a716-446655440000",
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "display_name": "Example Name"
        }
      ],
      "directory_id": "550e8400-e29b-41d4-a716-446655440000",
      "directory_enabled": true,
      "external_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "directory": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "directory_name": "Example Name",
    "provider": "Example Academy Trust",
    "enterprise_connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "display_name": "Example Name"
      }
    ],
    "directory_id": "550e8400-e29b-41d4-a716-446655440000",
    "directory_enabled": true,
    "external_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "scim": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "directory_name": "Example Name",
    "provider": "Example Academy Trust",
    "enterprise_connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "display_name": "Example Name"
      }
    ],
    "directory_id": "550e8400-e29b-41d4-a716-446655440000",
    "directory_enabled": true,
    "external_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Request

Response

Errors