Operations 4
Documentation
Documentation
https://workos.com/docs
APIReference
https://workos.com/docs/reference
RateLimits
https://workos.com/docs/reference/rate-limits
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/workos:workos-api-keys-api"
All apis
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.
Get an API 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 Specification
openapi: 3.2.0
info:
title: WorkOS API Keys 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: API Keys
description: Manage API keys for environments.
x-displayName: API Keys
paths:
/api_keys/validations:
post:
description: Validate an API key value and return the API key object if valid.
operationId: ApiKeysController_validateApiKey
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateApiKeyDto'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyValidationResponse'
'401':
description: Unauthorized
'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
summary: Validate API Key
tags:
- API Keys
/api_keys/{id}:
delete:
description: Permanently deletes an API key. This action cannot be undone. Once deleted, any requests using this API key will fail authentication.
operationId: ApiKeysController_delete
parameters:
- name: id
required: true
in: path
description: The unique ID of the API key.
schema:
type: string
example: api_key_01EHZNVPK3SFK441A1RGBFSHRT
responses:
'204':
description: No Content
'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: Delete an API Key
tags:
- API Keys
/user_management/users/{userId}/api_keys:
get:
description: Get a list of API keys owned by a specific user.
operationId: UserApiKeysController_list
parameters:
- name: userId
required: true
in: path
description: Unique identifier of the user.
schema:
type: string
example: user_01EHZNVPK3SFK441A1RGBFSHRT
- 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.
schema:
example: obj_1234567890
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.
schema:
example: obj_1234567890
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.
schema:
$ref: '#/components/schemas/PaginationOrder'
- name: organization_id
required: false
in: query
description: The ID of the organization to filter user API keys by. When provided, only API keys created against that organization membership are returned.
schema:
example: org_01EHZNVPK3SFK441A1RGBFSHRT
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserApiKeyList'
'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: List API Keys for a User
tags:
- API Keys
x-feature-flag: user-api-keys
post:
description: Create a new API key owned by a user. The user must have an active membership in the specified organization.
operationId: UserApiKeysController_create
parameters:
- name: userId
required: true
in: path
description: Unique identifier of the user.
schema:
type: string
example: user_01EHZNVPK3SFK441A1RGBFSHRT
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserApiKeyDto'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/UserApiKeyWithValue'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: A human-readable description of the error.
example: Validation failed.
errors:
type: array
items:
type: object
properties:
code:
type: string
description: The validation error code.
example: required
field:
type: string
description: The field that failed validation.
example: event.action
required:
- code
- field
description: The list of validation errors.
required:
- message
- errors
'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
summary: Create an API Key for a User
tags:
- API Keys
x-feature-flag: user-api-keys
components:
schemas:
ValidateApiKeyDto:
type: object
properties:
value:
type: string
description: The value for an API key.
example: sk_example_1234567890abcdef
required:
- value
UserApiKeyWithValue:
type: object
properties:
object:
type: string
description: Distinguishes the API Key object.
const: api_key
id:
type: string
description: Unique identifier of the API Key.
example: api_key_01EHZNVPK3SFK441A1RGBFSHRT
owner:
type: object
properties:
type:
type: string
description: The type of the API Key owner.
example: user
const: user
id:
type: string
description: Unique identifier of the API Key owner.
example: user_01EHZNVPK3SFK441A1RGBFSHRT
organization_id:
type: string
description: Unique identifier of the organization the API Key can access.
example: org_01EHZNVPK3SFK441A1RGBFSHRT
required:
- type
- id
- organization_id
description: The entity that owns the API Key.
name:
type: string
description: A descriptive name for the API Key.
example: Production API Key
obfuscated_value:
type: string
description: An obfuscated representation of the API Key value.
example: sk_...3456
last_used_at:
type:
- string
- 'null'
format: date-time
description: Timestamp of when the API Key was last used.
example: null
permissions:
type: array
items:
type: string
description: The permission slugs assigned to the API Key.
example:
- posts:read
- posts:write
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'
value:
type: string
description: The full API Key value. Only returned once at creation time.
example: sk_abcdefghijklmnop123456
required:
- object
- id
- owner
- name
- obfuscated_value
- last_used_at
- permissions
- created_at
- updated_at
- value
CreateUserApiKeyDto:
type: object
properties:
name:
type: string
description: A descriptive name for the API key.
example: Production API Key
organization_id:
type: string
description: The ID of the organization the user API key is associated with. The user must have an active membership in this organization.
example: org_01EHZNVPK3SFK441A1RGBFSHRT
permissions:
description: The permission slugs to assign to the API key. Each permission must be enabled for user API keys.
example:
- posts:read
- posts:write
type: array
items:
type: string
required:
- name
- organization_id
ApiKeyValidationResponse:
type: object
properties:
api_key:
oneOf:
- $ref: '#/components/schemas/ApiKey'
- type: 'null'
required:
- api_key
PaginationOrder:
type: string
enum:
- normal
- desc
- asc
example: desc
default: desc
UserApiKeyList:
type: object
properties:
object:
type: string
description: Indicates this is a list response.
const: list
data:
type: array
items:
$ref: '#/components/schemas/UserApiKey'
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: api_key_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: api_key_01HXYZ987654321KJIHGFEDCBA
required:
- before
- after
description: Pagination cursors for navigating between pages of results.
required:
- object
- data
- list_metadata
ApiKey:
type: object
properties:
object:
type: string
description: Distinguishes the API Key object.
const: api_key
id:
type: string
description: Unique identifier of the API Key.
example: api_key_01EHZNVPK3SFK441A1RGBFSHRT
owner:
discriminator:
propertyName: type
oneOf:
- type: object
properties:
type:
type: string
description: The type of the API Key owner.
example: organization
const: organization
id:
type: string
description: Unique identifier of the API Key owner.
example: org_01EHZNVPK3SFK441A1RGBFSHRT
required:
- type
- id
- type: object
properties:
type:
type: string
description: The type of the API Key owner.
example: user
const: user
id:
type: string
description: Unique identifier of the API Key owner.
example: user_01EHZNVPK3SFK441A1RGBFSHRT
organization_id:
type: string
description: Unique identifier of the organization the API Key can access.
example: org_01EHZNVPK3SFK441A1RGBFSHRT
required:
- type
- id
- organization_id
description: The entity that owns the API Key.
example:
type: organization
id: org_01EHZNVPK3SFK441A1RGBFSHRT
name:
type: string
description: A descriptive name for the API Key.
example: Production API Key
obfuscated_value:
type: string
description: An obfuscated representation of the API Key value.
example: sk_...3456
last_used_at:
type:
- string
- 'null'
format: date-time
description: Timestamp of when the API Key was last used.
example: null
permissions:
type: array
items:
type: string
description: The permission slugs assigned to the API Key.
example:
- posts:read
- posts:write
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
- owner
- name
- obfuscated_value
- last_used_at
- permissions
- created_at
- updated_at
UserApiKey:
type: object
properties:
object:
type: string
description: Distinguishes the API Key object.
const: api_key
id:
type: string
description: Unique identifier of the API Key.
example: api_key_01EHZNVPK3SFK441A1RGBFSHRT
owner:
type: object
properties:
type:
type: string
description: The type of the API Key owner.
example: user
const: user
id:
type: string
description: Unique identifier of the API Key owner.
example: user_01EHZNVPK3SFK441A1RGBFSHRT
organization_id:
type: string
description: Unique identifier of the organization the API Key can access.
example: org_01EHZNVPK3SFK441A1RGBFSHRT
required:
- type
- id
- organization_id
description: The entity that owns the API Key.
name:
type: string
description: A descriptive name for the API Key.
example: Production API Key
obfuscated_value:
type: string
description: An obfuscated representation of the API Key value.
example: sk_...3456
last_used_at:
type:
- string
- 'null'
format: date-time
description: Timestamp of when the API Key was last used.
example: null
permissions:
type: array
items:
type: string
description: The permission slugs assigned to the API Key.
example:
- posts:read
- posts:write
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
- owner
- name
- obfuscated_value
- last_used_at
- permissions
- created_at
- updated_at
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.