Operations 2
Documentation
Documentation
https://workos.com/docs
APIReference
https://workos.com/docs/reference
RateLimits
https://workos.com/docs/reference/rate-limits
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/workos:workos-directory-users-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: WorkOS Directory Users API
description: WorkOS REST API
version: '1.0'
contact:
name: WorkOS
url: https://workos.com
email: support@workos.com
license:
name: MIT
url: https://opensource.org/license/MIT
servers:
- url: https://api.workos.com
description: Production
- url: https://api.workos-test.com
description: Staging
security:
- bearer: []
tags:
- name: directory-users
description: Manage directory users.
x-displayName: Directory Users
paths:
/directory_users:
get:
description: Get a list of all of existing Directory Users matching the criteria specified.
operationId: DirectoryUsersController_list
parameters:
- name: before
required: false
in: query
description: 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"`.
schema:
example: xxx_01HXYZ123456789ABCDEFGHIJ
type: string
- name: after
required: false
in: query
description: 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"`.
schema:
example: xxx_01HXYZ987654321KJIHGFEDCBA
type: string
- name: limit
required: false
in: query
description: Upper limit on the number of objects to return, between `1` and `100`.
schema:
minimum: 1
maximum: 100
default: 10
example: 10
type: integer
- name: order
required: false
in: query
description: 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 descending.
schema:
$ref: '#/components/schemas/PaginationOrder'
- name: directory
required: false
in: query
description: Unique identifier of the WorkOS Directory. This value can be obtained from the WorkOS dashboard or from the WorkOS API.
schema:
example: directory_01ECAZ4NV9QMV47GW873HDCX74
type: string
- name: group
required: false
in: query
description: Unique identifier of the WorkOS Directory Group. This value can be obtained from the WorkOS API.
schema:
example: directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryUserList'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
'422':
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
'429':
description: ''
content:
application/json:
schema:
type: string
const: Ratelimited
summary: List Directory Users
tags:
- directory-users
/directory_users/{id}:
get:
description: Get the details of an existing Directory User.
operationId: DirectoryUsersController_find
parameters:
- name: id
required: true
in: path
description: Unique identifier for the Directory User.
schema:
example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryUserWithGroups'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.'
required:
- message
summary: Get a Directory User
tags:
- directory-users
components:
schemas:
DirectoryUserWithGroups:
type: object
properties:
object:
type: string
description: Distinguishes the Directory User object.
const: directory_user
id:
type: string
description: Unique identifier for the Directory User.
example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ
directory_id:
type: string
description: The identifier of the Directory the Directory User belongs to.
example: directory_01ECAZ4NV9QMV47GW873HDCX74
organization_id:
type: string
description: The identifier for the Organization in which the Directory resides.
example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y
idp_id:
type: string
description: Unique identifier for the user, assigned by the Directory Provider. Different Directory Providers use different ID formats.
example: '2836'
email:
type:
- string
- 'null'
description: The email address of the user.
example: marcelina.davis@example.com
first_name:
type:
- string
- 'null'
description: The first name of the user.
example: Marcelina
last_name:
type:
- string
- 'null'
description: The last name of the user.
example: Davis
name:
type:
- string
- 'null'
description: The full name of the user.
example: Marcelina Davis
emails:
type: array
items:
type: object
properties:
primary:
type: boolean
description: Whether this is the primary email address.
example: true
type:
type: string
description: The type of email address.
example: work
value:
type:
- string
- 'null'
description: The email address value.
example: marcelina.davis@example.com
description: A list of email addresses for the user.
deprecated: true
job_title:
type:
- string
- 'null'
description: The job title of the user.
example: Software Engineer
deprecated: true
username:
type:
- string
- 'null'
description: The username of the user.
example: mdavis
deprecated: true
state:
type: string
enum:
- active
- suspended
- inactive
description: The state of the user.
example: active
raw_attributes:
type: object
additionalProperties: {}
description: The raw attributes received from the directory provider.
deprecated: true
custom_attributes:
type: object
additionalProperties: {}
description: An object containing the custom attribute mapping for the Directory Provider.
example:
department: Engineering
job_title: Software Engineer
role:
$ref: '#/components/schemas/SlimRole'
roles:
type: array
items:
$ref: '#/components/schemas/SlimRole'
description: All roles assigned to the user.
created_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
updated_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
groups:
type: array
items:
$ref: '#/components/schemas/DirectoryGroup'
description: 'The directory groups the user belongs to. Deprecated: starting May 1, 2026, this field returns an empty array by default for newly created teams. Existing teams currently depending on this field should migrate to the new access pattern for better throughput performance — the field is unbounded by user, so users with many group memberships produce large, slow response payloads. Use the List Directory Groups endpoint with a `user` filter to fetch a user''s group memberships.'
deprecated: true
required:
- object
- id
- directory_id
- organization_id
- idp_id
- email
- state
- raw_attributes
- custom_attributes
- created_at
- updated_at
- groups
SlimRole:
type: object
properties:
slug:
type: string
description: The slug of the assigned role.
example: admin
required:
- slug
description: The primary role assigned to the user.
DirectoryUserList:
type: object
properties:
object:
type: string
description: Indicates this is a list response.
const: list
data:
type: array
items:
$ref: '#/components/schemas/DirectoryUserWithGroups'
description: The list of records for the current page.
list_metadata:
type: object
properties:
before:
type:
- string
- 'null'
description: An object ID that defines your place in the list. When the ID is not present, you are at the start of the list.
example: directory_user_01HXYZ123456789ABCDEFGHIJ
after:
type:
- string
- 'null'
description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
example: directory_user_01HXYZ987654321KJIHGFEDCBA
required:
- before
- after
description: Pagination cursors for navigating between pages of results.
required:
- object
- data
- list_metadata
- list_metadata
DirectoryGroup:
type: object
properties:
object:
type: string
description: Distinguishes the Directory Group object.
const: directory_group
id:
type: string
description: Unique identifier for the Directory Group.
example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z
idp_id:
type: string
description: Unique identifier for the group, assigned by the Directory Provider. Different Directory Providers use different ID formats.
example: 02grqrue4294w24
directory_id:
type: string
description: The identifier of the Directory the Directory Group belongs to.
example: directory_01ECAZ4NV9QMV47GW873HDCX74
organization_id:
type: string
description: The identifier for the Organization in which the Directory resides.
example: org_01EZTR6WYX1A0DSE2CYMGXQ24Y
name:
type: string
description: The name of the Directory Group.
example: Developers
raw_attributes:
type: object
additionalProperties: {}
description: The raw attributes received from the directory provider.
created_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
updated_at:
format: date-time
type: string
description: An ISO 8601 timestamp.
example: '2026-01-15T12:00:00.000Z'
required:
- object
- id
- idp_id
- directory_id
- organization_id
- name
- created_at
- updated_at
PaginationOrder:
type: string
enum:
- normal
- desc
- asc
example: desc
default: desc
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
description: 'Your WorkOS API key prefixed with `sk_`. Pass it as a Bearer token: `Authorization: Bearer sk_example_123456789`.'
access_token:
scheme: bearer
bearerFormat: JWT
type: http
description: An SSO access token returned from the Get a Profile and Token endpoint.