From 50e3b5587862ac1381d6f714ac08168e047dbd78 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Mon, 4 May 2026 15:01:28 -0700 Subject: [PATCH 01/17] feat(api): add generic `workos api` gateway for raw API requests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds `workos api` command that provides direct, authenticated access to any WorkOS API endpoint without needing a dedicated command per resource. Three modes: - `workos api ls [filter]` — list endpoints from the embedded OpenAPI spec - `workos api ` — make authenticated GET/POST/PUT/PATCH/DELETE - Flags: -X method, -d data, --file, --include, --dry-run, --yes The OpenAPI spec (170 endpoints, 40 tags) is embedded at build time from the workos-openapi-spec repo. Auth resolves from the active environment automatically (same as existing resource commands). --- src/bin.ts | 76 + src/commands/api/catalog.ts | 101 + src/commands/api/index.ts | 190 + src/commands/api/request.ts | 56 + src/commands/api/workos-openapi-spec.yaml | 31661 ++++++++++++++++++++ src/utils/help-json.ts | 65 + 6 files changed, 32149 insertions(+) create mode 100644 src/commands/api/catalog.ts create mode 100644 src/commands/api/index.ts create mode 100644 src/commands/api/request.ts create mode 100644 src/commands/api/workos-openapi-spec.yaml diff --git a/src/bin.ts b/src/bin.ts index bdbf96b..e860c8e 100644 --- a/src/bin.ts +++ b/src/bin.ts @@ -430,6 +430,82 @@ yargs(rawArgs) ); return yargs.demandCommand(1, 'Please specify an env subcommand').strict(); }) + .command( + 'api [endpoint] [filter]', + 'Make authenticated requests to the WorkOS API', + (yargs) => + yargs + .positional('endpoint', { + type: 'string', + describe: "API endpoint path (e.g. /users), or 'ls' to list endpoints", + }) + .positional('filter', { + type: 'string', + describe: 'Filter keyword (used with ls)', + }) + .option('method', { + alias: 'X', + type: 'string', + describe: 'HTTP method (default: GET, or POST if body provided)', + }) + .option('data', { + alias: 'd', + type: 'string', + describe: 'JSON request body', + }) + .option('file', { + type: 'string', + describe: 'Read request body from a file (or - for stdin)', + }) + .option('include', { + alias: 'i', + type: 'boolean', + default: false, + describe: 'Show response headers', + }) + .option('api-key', { + type: 'string', + describe: 'Override the API key', + }) + .option('dry-run', { + type: 'boolean', + default: false, + describe: 'Show the request without executing it', + }) + .option('yes', { + alias: 'y', + type: 'boolean', + default: false, + describe: 'Skip confirmation for mutating requests', + }) + .example('workos api ls', 'List all available endpoints') + .example('workos api ls users', 'List endpoints matching "users"') + .example('workos api /user_management/users', 'GET /user_management/users') + .example('workos api /organizations -d \'{"name":"Acme"}\'', 'POST with a JSON body') + .example('workos api /organizations/org_123 -X DELETE', 'DELETE an organization'), + async (argv) => { + await applyInsecureStorage(argv.insecureStorage as boolean | undefined); + const endpoint = argv.endpoint as string | undefined; + const filter = argv.filter as string | undefined; + + const { runApiLs, runApiRequest } = await import('./commands/api/index.js'); + + if (!endpoint || endpoint === 'ls') { + runApiLs(filter); + return; + } + + await runApiRequest(endpoint, { + method: argv.method, + data: argv.data, + file: argv.file, + include: argv.include, + apiKey: argv.apiKey, + dryRun: argv.dryRun, + yes: argv.yes, + }); + }, + ) .command(['organization', 'org'], 'Manage WorkOS organizations (create, update, get, list, delete)', (yargs) => { yargs.options({ ...insecureStorageOption, diff --git a/src/commands/api/catalog.ts b/src/commands/api/catalog.ts new file mode 100644 index 0000000..941c5da --- /dev/null +++ b/src/commands/api/catalog.ts @@ -0,0 +1,101 @@ +/** + * OpenAPI catalog: parsing the embedded spec into a queryable endpoint list. + */ + +import { parse as parseYaml } from 'yaml'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { dirname, join } from 'node:path'; + +export interface PathParam { + name: string; + description: string; + required: boolean; +} + +export interface QueryParam { + name: string; + description: string; + required: boolean; +} + +export interface EndpointInfo { + method: string; + path: string; + summary: string; + tag: string; + operationId: string; + pathParams: PathParam[]; + queryParams: QueryParam[]; + hasRequestBody: boolean; +} + +export interface Catalog { + endpoints: EndpointInfo[]; + tags: string[]; +} + +const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const; + +export function parseSpec(yamlText: string): Catalog { + const spec = parseYaml(yamlText); + const endpoints: EndpointInfo[] = []; + + for (const [path, pathItem] of Object.entries(spec.paths ?? {})) { + const pathObj = pathItem as Record; + + for (const method of HTTP_METHODS) { + const operation = pathObj[method]; + if (!operation || typeof operation !== 'object') continue; + + const op = operation as Record; + const tag = ((op.tags as string[]) ?? ['other'])[0] ?? 'other'; + + const allParams = [...((pathObj.parameters as unknown[]) ?? []), ...((op.parameters as unknown[]) ?? [])]; + + const pathParams: PathParam[] = allParams + .filter((p: any) => p.in === 'path') + .map((p: any) => ({ name: p.name, description: p.description ?? '', required: p.required ?? true })); + + const queryParams: QueryParam[] = allParams + .filter((p: any) => p.in === 'query') + .map((p: any) => ({ name: p.name, description: p.description ?? '', required: p.required ?? false })); + + endpoints.push({ + method: method.toUpperCase(), + path, + summary: (op.summary as string) ?? '', + tag, + operationId: (op.operationId as string) ?? '', + pathParams, + queryParams, + hasRequestBody: !!op.requestBody, + }); + } + } + + const tags = [...new Set(endpoints.map((e) => e.tag))].sort(); + return { endpoints, tags }; +} + +let cachedCatalog: Catalog | undefined; + +export function loadCatalog(): Catalog { + if (cachedCatalog) return cachedCatalog; + + const specDir = dirname(fileURLToPath(import.meta.url)); + const specPath = join(specDir, 'workos-openapi-spec.yaml'); + const yamlText = readFileSync(specPath, 'utf-8'); + cachedCatalog = parseSpec(yamlText); + return cachedCatalog; +} + +export function endpointsByTag(catalog: Catalog): Map { + const grouped = new Map(); + for (const ep of catalog.endpoints) { + const list = grouped.get(ep.tag) ?? []; + list.push(ep); + grouped.set(ep.tag, list); + } + return grouped; +} diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts new file mode 100644 index 0000000..e399522 --- /dev/null +++ b/src/commands/api/index.ts @@ -0,0 +1,190 @@ +/** + * `workos api` — generic authenticated API gateway. + * + * Modes: + * workos api ls [filter] — list endpoints from the embedded OpenAPI spec + * workos api [opts] — make an authenticated request + */ + +import chalk from 'chalk'; +import { readFileSync } from 'node:fs'; +import { loadCatalog, endpointsByTag } from './catalog.js'; +import { apiRequest } from './request.js'; +import { resolveApiKey, resolveApiBaseUrl } from '../../lib/api-key.js'; +import { isJsonMode, outputJson } from '../../utils/output.js'; +import { isNonInteractiveEnvironment } from '../../utils/environment.js'; + +export interface ApiCommandOptions { + method?: string; + data?: string; + file?: string; + include?: boolean; + apiKey?: string; + dryRun?: boolean; + yes?: boolean; +} + +const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']); + +// ── ls ───────────────────────────────────────────────────────────────── + +export function runApiLs(filter?: string): void { + const catalog = loadCatalog(); + let endpoints = catalog.endpoints; + + if (filter) { + const lower = filter.toLowerCase(); + endpoints = endpoints.filter( + (e) => + e.path.toLowerCase().includes(lower) || + e.tag.toLowerCase().includes(lower) || + e.summary.toLowerCase().includes(lower) || + e.operationId.toLowerCase().includes(lower), + ); + } + + if (endpoints.length === 0) { + if (isJsonMode()) { + outputJson({ data: [] }); + } else { + console.log(filter ? `No endpoints matching "${filter}".` : 'No endpoints found.'); + } + return; + } + + if (isJsonMode()) { + outputJson({ + data: endpoints.map((e) => ({ + method: e.method, + path: e.path, + summary: e.summary, + tag: e.tag, + })), + }); + return; + } + + const grouped = endpointsByTag({ endpoints, tags: [...new Set(endpoints.map((e) => e.tag))].sort() }); + + for (const [tag, eps] of grouped) { + console.log(`\n${chalk.bold(tag)}`); + for (const ep of eps) { + const method = colorMethod(ep.method).padEnd(18); // padEnd accounts for ANSI codes + console.log(` ${method} ${ep.path} ${chalk.dim(ep.summary)}`); + } + } + console.log(); +} + +// ── request ──────────────────────────────────────────────────────────── + +export async function runApiRequest(endpoint: string, options: ApiCommandOptions): Promise { + const body = await resolveBody(options); + const method = (options.method ?? (body ? 'POST' : 'GET')).toUpperCase(); + const apiKey = options.apiKey ?? resolveApiKey(); + const baseUrl = resolveApiBaseUrl(); + + if (options.dryRun) { + if (isJsonMode()) { + outputJson({ + dryRun: true, + method, + url: `${baseUrl}${normalizePath(endpoint)}`, + body: body ? JSON.parse(body) : undefined, + }); + } else { + console.log(`${chalk.dim('[dry-run]')} ${method} ${baseUrl}${normalizePath(endpoint)}`); + if (body) prettyPrint(body); + } + return; + } + + if (MUTATING_METHODS.has(method) && !options.yes && !isNonInteractiveEnvironment()) { + const clack = (await import('../../utils/clack.js')).default; + console.log(`\n${chalk.yellow('About to')} ${method} ${endpoint}`); + if (body) prettyPrint(body); + const ok = await clack.confirm({ message: 'Proceed?' }); + if (!ok || clack.isCancel(ok)) { + process.exit(0); + } + } + + const response = await apiRequest({ + method, + path: normalizePath(endpoint), + apiKey, + body: body ?? undefined, + baseUrl, + }); + + if (options.include) { + printHeaders(response.status, response.headers); + } + + if (isJsonMode()) { + outputJson(response.body); + } else if (typeof response.body === 'object' && response.body !== null) { + console.log(JSON.stringify(response.body, null, 2)); + } else { + console.log(response.rawBody); + } + + if (response.status >= 400) { + process.exit(1); + } +} + +// ── helpers ──────────────────────────────────────────────────────────── + +function normalizePath(path: string): string { + if (!path.startsWith('/')) return `/${path}`; + return path; +} + +async function resolveBody(options: ApiCommandOptions): Promise { + if (options.data) return options.data; + if (options.file) { + if (options.file === '-') { + const chunks: Buffer[] = []; + for await (const chunk of process.stdin) { + chunks.push(chunk); + } + return Buffer.concat(chunks).toString('utf-8'); + } + return readFileSync(options.file, 'utf-8'); + } + return null; +} + +function prettyPrint(jsonString: string): void { + try { + console.log(JSON.stringify(JSON.parse(jsonString), null, 2)); + } catch { + console.log(jsonString); + } +} + +function printHeaders(status: number, headers: Headers): void { + console.log(chalk.dim(`HTTP ${status}`)); + headers.forEach((value, key) => { + console.log(chalk.dim(`${key}: ${value}`)); + }); + console.log(); +} + +function colorMethod(method: string): string { + switch (method) { + case 'GET': + return chalk.green(method); + case 'POST': + return chalk.blue(method); + case 'PUT': + return chalk.yellow(method); + case 'PATCH': + return chalk.yellow(method); + case 'DELETE': + return chalk.red(method); + default: + return method; + } +} diff --git a/src/commands/api/request.ts b/src/commands/api/request.ts new file mode 100644 index 0000000..79589a5 --- /dev/null +++ b/src/commands/api/request.ts @@ -0,0 +1,56 @@ +/** + * Raw API request executor for `workos api `. + */ + +import { resolveApiKey, resolveApiBaseUrl } from '../../lib/api-key.js'; + +export interface ApiRequestOptions { + method: string; + path: string; + apiKey?: string; + body?: string; + baseUrl?: string; +} + +export interface ApiResponse { + status: number; + headers: Headers; + body: unknown; + rawBody: string; +} + +export async function apiRequest(options: ApiRequestOptions): Promise { + const apiKey = options.apiKey ?? resolveApiKey(); + const baseUrl = options.baseUrl ?? resolveApiBaseUrl(); + + let path = options.path; + if (!path.startsWith('/')) path = `/${path}`; + + const url = `${baseUrl}${path}`; + + const headers: Record = { + Authorization: `Bearer ${apiKey}`, + Accept: 'application/json', + }; + + if (options.body) { + headers['Content-Type'] = 'application/json'; + } + + const response = await fetch(url, { + method: options.method, + headers, + body: options.body ?? undefined, + }); + + const rawBody = await response.text(); + + let body: unknown; + try { + body = JSON.parse(rawBody); + } catch { + body = rawBody; + } + + return { status: response.status, headers: response.headers, body, rawBody }; +} diff --git a/src/commands/api/workos-openapi-spec.yaml b/src/commands/api/workos-openapi-spec.yaml new file mode 100644 index 0000000..d30c2e8 --- /dev/null +++ b/src/commands/api/workos-openapi-spec.yaml @@ -0,0 +1,31661 @@ +openapi: 3.1.1 +paths: + /api_keys/validations: + post: + operationId: ApiKeysController_validateApiKey + summary: Validate API key + description: Validate an API key value and return the API key object if valid. + 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 + tags: + - api_keys + /api_keys/{id}: + delete: + operationId: ApiKeysController_delete + summary: Delete an API key + description: >- + Permanently deletes an API key. This action cannot be undone. Once + deleted, any requests using this API key will fail authentication. + 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 + tags: + - api_keys + /audit_logs/actions: + get: + operationId: AuditLogValidatorsController_list + summary: List Actions + description: Get a list of all Audit Log actions in the current environment. + 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. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + 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: ala_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: ala_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: + type: array + description: The list of records for the current page. + items: + $ref: '#/components/schemas/AuditLogActionJson' + '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 + tags: + - audit-logs + /audit_logs/actions/{actionName}/schemas: + post: + operationId: AuditLogValidatorVersionsController_create + summary: Create Schema + description: >- + Creates a new Audit Log schema used to validate the payload of incoming + Audit Log Events. If the `action` does not exist, it will also be + created. + parameters: + - name: actionName + required: true + in: path + description: The name of the Audit Log action. + schema: + example: user.logged_in + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogSchemaDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogSchemaJson' + '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 + tags: + - audit-logs + get: + operationId: AuditLogValidatorVersionsController_schemas + summary: List Schemas + description: >- + Get a list of all schemas for the Audit Logs action identified by + `:name`. + parameters: + - name: actionName + required: true + in: path + description: The name of the Audit Log action. + schema: + example: user.logged_in + type: string + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + 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: als_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: als_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: + type: array + description: The list of records for the current page. + items: + $ref: '#/components/schemas/AuditLogSchemaJson' + '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 + tags: + - audit-logs + /audit_logs/events: + post: + operationId: AuditLogEventsController_create + summary: Create Event + description: >- + Create an Audit Log Event. + + + This API supports idempotency which guarantees that performing the same + operation multiple times will have the same result as if the operation + were performed only once. This is handy in situations where you may need + to retry a request due to a failure or prevent accidental duplicate + requests from creating more than one resource. + + + To achieve idempotency, you can add `Idempotency-Key` request header to + a Create Event request with a unique string as the value. Each + subsequent request matching this unique string will return the same + response. We suggest using [v4 + UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) for + idempotency keys to avoid collisions. + + + Idempotency keys expire after 24 hours. The API will generate a new + response if you submit a request with an expired key. + parameters: + - name: idempotency-key + in: header + description: >- + A unique string to prevent duplicate requests. Each subsequent + request matching this unique string will return the same response. + We suggest using v4 UUIDs. Keys expire after 24 hours. + required: false + schema: + type: string + example: 884793cd-bef4-46cf-8790-e3d4957a09ce + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogEventIngestionDto' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogEventCreateResponse' + example: + success: true + description: OK + '400': + content: + application/json: + schema: + anyOf: + - type: object + properties: + errors: + type: array + items: + type: object + properties: + instancePath: + type: string + description: >- + The JSON path to the invalid field in the event + payload. + example: /targets + required: + - instancePath + description: The list of validation errors. + message: + type: string + description: A human-readable description of the error. + example: Invalid Audit Log event. + code: + type: string + description: The error code identifying the type of error. + example: invalid_audit_log_event + required: + - errors + - message + - code + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Organization not found: + 'org_01EHQMYV6MBK39QC5PZXHY59C3'. + required: + - message + example: + message: Invalid Audit Log event. + code: invalid_audit_log_event + errors: + - instancePath: /targets + description: Bad Request + '404': + 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 + example: + message: "Organization not found: 'org_01EHQMYV6MBK39QC5PZXHY59C3'." + description: Not Found + '422': + content: + application/json: + schema: + type: object + properties: + 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. + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - errors + - message + example: + message: Validation failed. + errors: + - code: required + field: event.action + description: Unprocessable Entity + '429': + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Too many requests. + code: + type: string + description: The error code identifying the type of error. + example: rate_limit_exceeded + required: + - message + - code + example: + message: Too many requests. + code: rate_limit_exceeded + description: '' + tags: + - audit-logs + /audit_logs/exports: + post: + operationId: AuditLogExportsController_exports + summary: Create Export + description: >- + Create an Audit Log Export. Exports are scoped to a single organization + within a specified date range. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportCreationDto' + responses: + '201': + description: The created Audit Log Export object. + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportJson' + example: + object: audit_log_export + id: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V + state: pending + created_at: '2022-09-02T17:14:57.094Z' + updated_at: '2022-09-02T17:14:57.094Z' + '400': + description: Invalid request parameters or date range. + content: + application/json: + schema: + anyOf: + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Organization not found: + 'org_01EHQMYV6MBK39QC5PZXHY59C3'. + required: + - message + - type: object + properties: + message: + type: array + items: + type: string + description: >- + A list of human-readable error messages describing the + validation failures. + example: + - Invalid date range + error: + type: string + description: The error type. + example: Bad Request + required: + - message + - error + example: + message: Invalid date range + code: invalid_audit_log_export_range_date + tags: + - audit-logs + /audit_logs/exports/{auditLogExportId}: + get: + operationId: AuditLogExportsController_export + summary: Get Export + description: >- + Get an Audit Log Export. The URL will expire after 10 minutes. If the + export is needed again at a later time, refetching the export will + regenerate the URL. + parameters: + - name: auditLogExportId + required: true + in: path + description: The unique ID of the Audit Log Export. + schema: + type: string + example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V + responses: + '200': + description: The Audit Log Export object. + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogExportJson' + example: + 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' + '404': + description: Audit Log Export 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 + example: + message: >- + Audit Log Export not found: + 'audit_log_export_01GBZK5MP7TD1YCFQHFR22180V'. + tags: + - audit-logs + /auth/challenges/{id}/verify: + post: + operationId: AuthenticationChallengesController_verify + summary: Verify Challenge + description: Verifies an Authentication Challenge. + parameters: + - name: id + required: true + in: path + description: The unique ID of the Authentication Challenge. + schema: + type: string + example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The one-time code to verify. + example: '123456' + required: + - code + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/AuthenticationChallengeVerifyResponse' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: one_time_code_too_many_attempts + const: one_time_code_too_many_attempts + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - multi-factor-auth.challenges + /auth/factors/enroll: + post: + operationId: AuthenticationFactorsController_create + summary: Enroll Factor + description: >- + Enrolls an Authentication Factor to be used as an additional factor of + authentication. The returned ID should be used to create an + authentication Challenge. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + type: + type: string + enum: + - generic_otp + - sms + - totp + description: The type of factor to enroll. + example: totp + phone_number: + type: string + description: Required when type is 'sms'. + example: '+15555555555' + totp_issuer: + type: string + description: Required when type is 'totp'. + example: Foo Corp + totp_user: + type: string + description: Required when type is 'totp'. + example: alan.turing@example.com + user_id: + type: string + description: The ID of the user to associate the factor with. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + required: + - type + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/AuthenticationFactorEnrolled' + '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 + tags: + - multi-factor-auth + /auth/factors/{id}: + get: + operationId: AuthenticationFactorsController_get + summary: Get Factor + description: Gets an Authentication Factor. + parameters: + - name: id + required: true + in: path + description: The unique ID of the Factor. + schema: + type: string + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/AuthenticationFactor' + example: + 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' + description: OK + '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 + tags: + - multi-factor-auth + delete: + operationId: AuthenticationFactorsController_delete + summary: Delete Factor + description: Permanently deletes an Authentication Factor. It cannot be undone. + parameters: + - name: id + required: true + in: path + description: The unique ID of the Factor. + schema: + type: string + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + responses: + '200': + description: OK + '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 + tags: + - multi-factor-auth + /auth/factors/{id}/challenge: + post: + operationId: AuthenticationFactorsController_challenge + summary: Challenge Factor + description: Creates a Challenge for an Authentication Factor. + parameters: + - name: id + required: true + in: path + description: The unique ID of the Authentication Factor to be challenged. + schema: + type: string + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ChallengeAuthenticationFactorDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/AuthenticationChallenge' + '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 + tags: + - multi-factor-auth + /authkit/oauth2/complete: + post: + operationId: ExternalAuthController_completeLogin + summary: Complete external authentication + description: >- + Completes an external authentication flow and returns control to + AuthKit. This endpoint is used with [Standalone + Connect](/authkit/connect/standalone) to bridge your existing + authentication system with the Connect OAuth API infrastructure. + + + After successfully authenticating a user in your application, calling + this endpoint will: + + + - Create or update the user in AuthKit, using the given `id` as its + `external_id`. + + - Return a `redirect_uri` your application should redirect to in order + for AuthKit to complete the flow + + + Users are automatically created or updated based on the `id` and `email` + provided. If a user with the same `id` exists, their information is + updated. Otherwise, a new user is created. + + + If you provide a new `id` with an `email` that already belongs to an + existing user, the request will fail with an error as email addresses + are unique to a user. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UserManagementLoginRequest' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAuthCompleteResponse' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_auth_session_already_completed + const: external_auth_session_already_completed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_not_allowed + const: email_change_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_not_available + const: email_not_available + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_email + const: invalid_email + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + error: + type: string + description: The HTTP error type. + example: Bad Request + message: + type: string + description: A human-readable description of the error. + example: Claim "sub" is reserved and cannot be used. + required: + - error + - 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 + tags: + - workos-connect + /authorization/organization_memberships/{organization_membership_id}/check: + post: + operationId: AuthorizationController_check + summary: Check authorization + description: >- + Check if an organization membership has a specific permission on a + resource. Supports identification by resource_id OR by + resource_external_id + resource_type_slug. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership to check. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CheckAuthorizationDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationCheck' + '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 + tags: + - authorization + x-mutually-exclusive-body-groups: &ref_3 + resource_target: + optional: false + variants: + by_id: + - resource_id + by_external_id: + - resource_external_id + - resource_type_slug + /authorization/organization_memberships/{organization_membership_id}/resources: + get: + operationId: AuthorizationController_listResourcesForMembership + summary: List resources for organization membership + description: >- + Returns all child resources of a parent resource where the organization + membership has a specific permission. This is useful for resource + discovery—answering "What projects can this user access in this + workspace?" + + + You must provide either `parent_resource_id` or both + `parent_resource_external_id` and `parent_resource_type_slug` to + identify the parent resource. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: permission_slug + required: true + in: query + description: >- + The permission slug to filter by. Only child resources where the + organization membership has this permission are returned. + schema: + type: string + example: project:read + - name: parent_resource_id + required: false + in: query + description: >- + The WorkOS ID of the parent resource. Provide this or both + `parent_resource_external_id` and `parent_resource_type_slug`, but + not both. Mutually exclusive with `parent_resource_type_slug` and + `parent_resource_external_id`. + schema: + type: string + example: authz_resource_01XYZ789 + - name: parent_resource_type_slug + required: false + in: query + description: >- + The slug of the parent resource type. Must be provided together with + `parent_resource_external_id`. Required with + `parent_resource_external_id`. Mutually exclusive with + `parent_resource_id`. + schema: + type: string + example: project + - name: parent_resource_external_id + required: false + in: query + description: >- + The application-specific external identifier of the parent resource. + Must be provided together with `parent_resource_type_slug`. Required + with `parent_resource_type_slug`. Mutually exclusive with + `parent_resource_id`. + schema: + type: string + example: external_project_123 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResourceList' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + x-mutually-exclusive-parameter-groups: + parent_resource: + optional: false + variants: + by_id: + - parent_resource_id + by_external_id: + - parent_resource_type_slug + - parent_resource_external_id + /authorization/organization_memberships/{organization_membership_id}/resources/{resource_id}/permissions: + get: + operationId: AuthorizationController_listEffectivePermissions + summary: List effective permissions for an organization membership on a resource + description: >- + Returns all permissions the organization membership effectively has on a + resource, including permissions inherited through roles assigned to + ancestor resources. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + - name: resource_id + required: true + in: path + description: The ID of the authorization resource. + schema: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPermissionList' + '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 + tags: + - authorization + /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions: + get: + operationId: AuthorizationController_listEffectivePermissionsByExternalId + summary: >- + List effective permissions for an organization membership on a resource + by external ID + description: >- + Returns all permissions the organization membership effectively has on a + resource identified by its external ID, including permissions inherited + through roles assigned to ancestor resources. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + - name: resource_type_slug + required: true + in: path + description: The slug of the resource type. + schema: + type: string + example: document + - name: external_id + required: true + in: path + description: An identifier you provide to reference the resource in your system. + schema: + type: string + example: doc-456 + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPermissionList' + '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 + tags: + - authorization + /authorization/organization_memberships/{organization_membership_id}/role_assignments: + get: + operationId: AuthorizationRoleAssignmentsController_listRoleAssignments + summary: List role assignments + description: >- + List all role assignments for an organization membership. This returns + all roles that have been assigned to the user on resources, including + organization-level and sub-resource roles. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RoleAssignmentList' + '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 + tags: + - authorization + post: + operationId: AuthorizationRoleAssignmentsController_assignRole + summary: Assign a role + description: Assign a role to an organization membership on a specific resource. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AssignRoleDto' + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/RoleAssignment' + example: + object: role_assignment + id: role_assignment_01HXYZ123456789ABCDEFGH + role: + slug: editor + resource: + id: authz_resource_01HXYZ123456789ABCDEFGH + external_id: project-ext-456 + resource_type_slug: project + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + description: Created + '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 + tags: + - authorization + x-mutually-exclusive-body-groups: &ref_4 + resource_target: + optional: false + variants: + by_id: + - resource_id + by_external_id: + - resource_external_id + - resource_type_slug + delete: + operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria + summary: Remove a role assignment + description: Remove a role assignment by role slug and resource. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RemoveRoleDto' + responses: + '204': + description: Role assignment removed successfully. + '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 + tags: + - authorization + x-mutually-exclusive-body-groups: &ref_5 + resource_target: + optional: false + variants: + by_id: + - resource_id + by_external_id: + - resource_external_id + - resource_type_slug + /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}: + delete: + operationId: AuthorizationRoleAssignmentsController_removeRoleById + summary: Remove a role assignment by ID + description: Remove a role assignment using its ID. + parameters: + - name: organization_membership_id + required: true + in: path + description: The ID of the organization membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + - name: role_assignment_id + required: true + in: path + description: The ID of the role assignment to remove. + schema: + type: string + example: role_assignment_01HXYZ123456789ABCDEFGH + responses: + '204': + description: Role assignment removed successfully. + '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 + tags: + - authorization + /authorization/organizations/{organizationId}/roles: + post: + operationId: AuthorizationOrganizationRolesController_create + summary: Create a custom role + description: Create a new custom role for this organization. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateOrganizationRoleDto' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: org-billing-admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Billing Administrator + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage billing and invoices + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: OrganizationRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: organization_role_slug_conflict + const: organization_role_slug_conflict + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - authorization + get: + operationId: AuthorizationOrganizationRolesController_list + summary: List custom roles + description: >- + Get a list of all roles that apply to an organization. This includes + both environment roles and custom roles, returned in priority order. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RoleList' + '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 + tags: + - authorization + /authorization/organizations/{organizationId}/roles/{slug}: + get: + operationId: AuthorizationOrganizationRolesController_get + summary: Get a custom role + description: >- + Retrieve a role that applies to an organization by its slug. This can + return either an environment role or a custom role. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-billing-admin + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: org-billing-admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Billing Manager + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can view and export billing reports + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: OrganizationRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '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 + tags: + - authorization + patch: + operationId: AuthorizationOrganizationRolesController_update + summary: Update a custom role + description: >- + Update an existing custom role. Only the fields provided in the request + body will be updated. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-billing-admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationRoleDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: org-billing-admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Finance Administrator + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage all financial operations + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: OrganizationRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + delete: + operationId: AuthorizationOrganizationRolesController_delete + summary: Delete a custom role + description: Delete an existing custom role. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-admin + responses: + '204': + description: No Content + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: role_has_assignments + const: role_has_assignments + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: role_has_group_role_mappings + const: role_has_group_role_mappings + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - authorization + /authorization/organizations/{organizationId}/roles/{slug}/permissions: + put: + operationId: AuthorizationOrganizationRolePermissionsController_setPermissions + summary: Set permissions for a custom role + description: Replace all permissions on a custom role with the provided list. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SetRolePermissionsDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: org-admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Organization Admin + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: OrganizationRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + example: + - billing:read + - billing:write + - invoices:manage + - reports:view + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '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 + tags: + - authorization + post: + operationId: AuthorizationOrganizationRolePermissionsController_addPermission + summary: Add a permission to a custom role + description: >- + Add a single permission to a custom role. If the permission is already + assigned to the role, this operation has no effect. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AddRolePermissionDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: org-admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Organization Admin + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: OrganizationRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + example: + - reports:export + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}: + delete: + operationId: AuthorizationOrganizationRolePermissionsController_removePermission + summary: Remove a permission from a custom role + description: Remove a single permission from a custom role by its slug. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-admin + - name: permissionSlug + required: true + in: path + description: The slug of the permission to remove. + schema: + type: string + example: documents:read + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + '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 + tags: + - authorization + /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}: + get: + operationId: AuthorizationResourcesByExternalIdController_getByExternalId + summary: Get a resource by external ID + description: >- + Retrieve the details of an authorization resource by its external ID, + organization, and resource type. This is useful when you only have the + external ID from your system and need to fetch the full resource + details. + parameters: + - name: organization_id + required: true + in: path + description: The ID of the organization that owns the resource. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: resource_type_slug + required: true + in: path + description: The slug of the resource type. + schema: + type: string + example: project + - name: external_id + required: true + in: path + description: An identifier you provide to reference the resource in your system. + schema: + type: string + example: proj-456 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResource' + '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 + tags: + - authorization + patch: + operationId: AuthorizationResourcesByExternalIdController_updateByExternalId + summary: Update a resource by external ID + description: Update an existing authorization resource using its external ID. + parameters: + - name: organization_id + required: true + in: path + description: The ID of the organization that owns the resource. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: resource_type_slug + required: true + in: path + description: The slug of the resource type. + schema: + type: string + example: project + - name: external_id + required: true + in: path + description: An identifier you provide to reference the resource in your system. + schema: + type: string + example: proj-456 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAuthorizationResourceDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the Resource object. + const: authorization_resource + name: + type: string + description: A human-readable name for the Resource. + example: Updated Name + description: + type: + - string + - 'null' + description: An optional description of the Resource. + example: Updated description + organization_id: + type: string + description: The ID of the organization that owns the resource. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + parent_resource_id: + type: + - string + - 'null' + description: The ID of the parent resource, if this resource is nested. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: >- + An identifier you provide to reference the resource in + your system. + example: proj-456 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: project + 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 + - name + - description + - organization_id + - parent_resource_id + - id + - external_id + - resource_type_slug + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - authorization + x-mutually-exclusive-body-groups: &ref_0 + parent_resource: + optional: true + variants: + by_id: + - parent_resource_id + by_external_id: + - parent_resource_external_id + - parent_resource_type_slug + delete: + operationId: AuthorizationResourcesByExternalIdController_deleteByExternalId + summary: Delete an authorization resource by external ID + description: >- + Delete an authorization resource by organization, resource type, and + external ID. This also deletes all descendant resources. + parameters: + - name: organization_id + required: true + in: path + description: The ID of the organization that owns the resource. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: resource_type_slug + required: true + in: path + description: The slug of the resource type. + schema: + type: string + example: project + - name: external_id + required: true + in: path + description: An identifier you provide to reference the resource in your system. + schema: + type: string + example: proj-456 + - name: cascade_delete + required: false + in: query + description: >- + If true, deletes all descendant resources and role assignments. If + not set and the resource has children or assignments, the request + will fail. + schema: + type: boolean + default: false + example: false + responses: + '204': + description: No Content + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_has_dependents + const: resource_has_dependents + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - authorization + /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships: + get: + operationId: >- + AuthorizationResourcesByExternalIdController_listOrganizationMembershipsForResourceByExternalId + summary: List memberships for a resource by external ID + description: >- + Returns all organization memberships that have a specific permission on + a resource, using the resource's external ID. This is useful for + answering "Who can access this resource?" when you only have the + external ID. + parameters: + - name: organization_id + required: true + in: path + description: The ID of the organization that owns the resource. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: resource_type_slug + required: true + in: path + description: The slug of the resource type this resource belongs to. + schema: + example: project + type: string + - name: external_id + required: true + in: path + description: An identifier you provide to reference the resource in your system. + schema: + example: proj-456 + type: string + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: permission_slug + required: true + in: query + description: >- + The permission slug to filter by. Only users with this permission on + the resource are returned. + schema: + type: string + example: project:read + - name: assignment + required: false + in: query + description: >- + Filter by assignment type. Use "direct" for direct assignments only, + or "indirect" to include inherited assignments. + schema: + type: string + enum: + - direct + - indirect + example: direct + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + /authorization/permissions: + get: + operationId: AuthorizationPermissionsController_list + summary: List permissions + description: Get a list of all permissions in your WorkOS environment. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPermissionList' + '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 + tags: + - permissions + post: + operationId: AuthorizationPermissionsController_create + summary: Create a permission + description: >- + Create a new permission in your WorkOS environment. The permission can + then be assigned to environment roles and custom roles. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAuthorizationPermissionDto' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the Permission object. + const: permission + id: + type: string + description: Unique identifier of the Permission. + example: perm_01HXYZ123456789ABCDEFGHIJ + slug: + type: string + description: >- + A unique key to reference the permission. Must be + lowercase and contain only letters, numbers, hyphens, + underscores, colons, periods, and asterisks. + example: documents:read + name: + type: string + description: A descriptive name for the Permission. + example: View Documents + description: + type: + - string + - 'null' + description: An optional description of the Permission. + example: Allows viewing document contents + system: + type: boolean + description: >- + Whether the permission is a system permission. System + permissions are managed by WorkOS and cannot be deleted. + example: false + resource_type_slug: + type: string + description: >- + The slug of the resource type associated with the + permission. + example: document + 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 + - slug + - name + - description + - system + - resource_type_slug + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + '409': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: permission_slug_conflict + const: permission_slug_conflict + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - permissions + /authorization/permissions/{slug}: + get: + operationId: AuthorizationPermissionsController_find + summary: Get a permission + description: Retrieve a permission by its unique slug. + parameters: + - name: slug + required: true + in: path + description: >- + A unique key to reference the permission. Must be lowercase and + contain only letters, numbers, hyphens, underscores, colons, + periods, and asterisks. + schema: + example: documents:read + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPermission' + '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 + tags: + - permissions + patch: + operationId: AuthorizationPermissionsController_update + summary: Update a permission + description: >- + Update an existing permission. Only the fields provided in the request + body will be updated. + parameters: + - name: slug + required: true + in: path + description: >- + A unique key to reference the permission. Must be lowercase and + contain only letters, numbers, hyphens, underscores, colons, + periods, and asterisks. + schema: + example: documents:read + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAuthorizationPermissionDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPermission' + '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 + tags: + - permissions + delete: + operationId: AuthorizationPermissionsController_delete + summary: Delete a permission + description: Delete an existing permission. System permissions cannot be deleted. + parameters: + - name: slug + required: true + in: path + description: >- + A unique key to reference the permission. Must be lowercase and + contain only letters, numbers, hyphens, underscores, colons, + periods, and asterisks. + schema: + example: documents:read + type: string + responses: + '204': + description: No Content + '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 + tags: + - permissions + /authorization/resources: + get: + operationId: AuthorizationResourcesController_list + summary: List resources + description: Get a paginated list of authorization resources. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization_id + required: false + in: query + description: Filter resources by organization ID. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: resource_type_slug + required: false + in: query + description: Filter resources by resource type slug. + schema: + type: string + example: project + - name: resource_external_id + required: false + in: query + description: Filter resources by external ID. + schema: + type: string + example: my-project-123 + - name: parent_resource_id + required: false + in: query + description: >- + Filter resources by parent resource ID. Mutually exclusive with + `parent_resource_type_slug` and `parent_external_id`. + schema: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + - name: parent_resource_type_slug + required: false + in: query + description: >- + Filter resources by parent resource type slug. Required with + `parent_external_id`. Mutually exclusive with `parent_resource_id`. + schema: + type: string + example: workspace + - name: parent_external_id + required: false + in: query + description: >- + Filter resources by parent external ID. Required with + `parent_resource_type_slug`. Mutually exclusive with + `parent_resource_id`. + schema: + type: string + example: ext-workspace-123 + - name: search + required: false + in: query + description: Search resources by name. + schema: + type: string + example: Website Redesign + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResourceList' + '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 + '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 + tags: + - authorization + x-mutually-exclusive-parameter-groups: + parent: + optional: true + variants: + by_id: + - parent_resource_id + by_external_id: + - parent_resource_type_slug + - parent_external_id + post: + operationId: AuthorizationResourcesController_create + summary: Create an authorization resource + description: Create a new authorization resource. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAuthorizationResourceDto' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the Resource object. + const: authorization_resource + name: + type: string + description: A human-readable name for the Resource. + example: Acme Workspace + description: + type: + - string + - 'null' + description: An optional description of the Resource. + example: Primary workspace for the Acme team + organization_id: + type: string + description: The ID of the organization that owns the resource. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + parent_resource_id: + type: + - string + - 'null' + description: The ID of the parent resource, if this resource is nested. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: >- + An identifier you provide to reference the resource in + your system. + example: my-workspace-01 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: workspace + 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 + - name + - description + - organization_id + - parent_resource_id + - id + - external_id + - resource_type_slug + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: authorization_resource_external_id_conflict + const: authorization_resource_external_id_conflict + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - authorization + x-mutually-exclusive-body-groups: &ref_6 + parent_resource: + optional: true + variants: + by_id: + - parent_resource_id + by_external_id: + - parent_resource_external_id + - parent_resource_type_slug + /authorization/resources/{resource_id}: + get: + operationId: AuthorizationResourcesController_findById + summary: Get a resource + description: Retrieve the details of an authorization resource by its ID. + parameters: + - name: resource_id + required: true + in: path + description: The ID of the authorization resource. + schema: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResource' + '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 + tags: + - authorization + patch: + operationId: AuthorizationResourcesController_update + summary: Update a resource + description: Update an existing authorization resource. + parameters: + - name: resource_id + required: true + in: path + description: The ID of the authorization resource. + schema: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAuthorizationResourceDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the Resource object. + const: authorization_resource + name: + type: string + description: A human-readable name for the Resource. + example: Updated Name + description: + type: + - string + - 'null' + description: An optional description of the Resource. + example: Updated description + organization_id: + type: string + description: The ID of the organization that owns the resource. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + parent_resource_id: + type: + - string + - 'null' + description: The ID of the parent resource, if this resource is nested. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: >- + An identifier you provide to reference the resource in + your system. + example: proj-456 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: project + 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 + - name + - description + - organization_id + - parent_resource_id + - id + - external_id + - resource_type_slug + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - authorization + x-mutually-exclusive-body-groups: *ref_0 + delete: + operationId: AuthorizationResourcesController_delete + summary: Delete an authorization resource + description: Delete an authorization resource and all its descendants. + parameters: + - name: resource_id + required: true + in: path + description: The ID of the authorization resource. + schema: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + - name: cascade_delete + required: false + in: query + description: >- + If true, deletes all descendant resources and role assignments. If + not set and the resource has children or assignments, the request + will fail. + schema: + type: boolean + default: false + example: false + responses: + '204': + description: No Content + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: lock_timeout + const: lock_timeout + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_has_dependents + const: resource_has_dependents + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: resource_type_update_in_progress + const: resource_type_update_in_progress + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - authorization + /authorization/resources/{resource_id}/organization_memberships: + get: + operationId: AuthorizationResourcesController_listOrganizationMembershipsForResource + summary: List organization memberships for resource + description: >- + Returns all organization memberships that have a specific permission on + a resource instance. This is useful for answering "Who can access this + resource?". + parameters: + - name: resource_id + required: true + in: path + description: The ID of the authorization resource. + schema: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: permission_slug + required: true + in: query + description: >- + The permission slug to filter by. Only users with this permission on + the resource are returned. + schema: + type: string + example: document:edit + - name: assignment + required: false + in: query + description: >- + Filter by assignment type. Use `direct` for direct assignments only, + or `indirect` to include inherited assignments. + schema: + type: string + enum: + - direct + - indirect + example: direct + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + /authorization/roles: + post: + operationId: AuthorizationRolesController_create + summary: Create an environment role + description: Create a new environment role. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateRoleDto' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: editor + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Editor + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can edit resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: EnvironmentRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: role_slug_conflict + const: role_slug_conflict + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - authorization + get: + operationId: AuthorizationRolesController_list + summary: List environment roles + description: List all environment roles in priority order. + parameters: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RoleList' + '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 + tags: + - authorization + /authorization/roles/{slug}: + get: + operationId: AuthorizationRolesController_get + summary: Get an environment role + description: Get an environment role by its slug. + parameters: + - name: slug + required: true + in: path + description: The slug of the environment role. + schema: + type: string + example: admin + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Role' + '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 + tags: + - authorization + patch: + operationId: AuthorizationRolesController_update + summary: Update an environment role + description: Update an existing environment role. + parameters: + - name: slug + required: true + in: path + description: The slug of the environment role. + schema: + type: string + example: admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateRoleDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Super Administrator + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Full administrative access to all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: EnvironmentRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + /authorization/roles/{slug}/permissions: + put: + operationId: AuthorizationRolePermissionsController_setPermissions + summary: Set permissions for an environment role + description: Replace all permissions on an environment role with the provided list. + parameters: + - name: slug + required: true + in: path + description: The slug of the environment role. + schema: + type: string + example: admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SetRolePermissionsDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Admin + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: EnvironmentRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + example: + - billing:read + - billing:write + - invoices:manage + - reports:view + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + post: + operationId: AuthorizationRolePermissionsController_addPermission + summary: Add a permission to an environment role + description: >- + Add a single permission to an environment role. If the permission is + already assigned to the role, this operation has no effect. + parameters: + - name: slug + required: true + in: path + description: The slug of the environment role. + schema: + type: string + example: admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AddRolePermissionDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Admin + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an + organization (custom role). + example: EnvironmentRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + example: + - reports:export + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - authorization + /connect/applications: + get: + operationId: ApplicationsController_list + summary: List Connect Applications + description: >- + List all Connect Applications in the current environment with optional + filtering. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization_id + required: false + in: query + description: Filter Connect Applications by organization ID. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectApplicationList' + '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 + tags: + - applications + post: + operationId: ApplicationsController_create + summary: Create a Connect Application + description: >- + Create a new Connect Application. Supports both OAuth and + Machine-to-Machine (M2M) application types. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/CreateOAuthApplicationDto' + - $ref: '#/components/schemas/CreateM2MApplicationDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectApplication' + '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 + tags: + - applications + /connect/applications/{id}: + get: + operationId: ApplicationsController_find + summary: Get a Connect Application + description: Retrieve details for a specific Connect Application by ID or client ID. + parameters: + - name: id + required: true + in: path + description: The application ID or client ID of the Connect Application. + schema: + type: string + example: conn_app_01HXYZ123456789ABCDEFGHIJ + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectApplication' + '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 + tags: + - applications + put: + operationId: ApplicationsController_update + summary: Update a Connect Application + description: >- + Update an existing Connect Application. For OAuth applications, you can + update redirect URIs. For all applications, you can update the name, + description, and scopes. + parameters: + - name: id + required: true + in: path + description: The application ID or client ID of the Connect Application. + schema: + type: string + example: conn_app_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOAuthApplicationDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectApplication' + '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 + tags: + - applications + delete: + operationId: ApplicationsController_delete + summary: Delete a Connect Application + description: Delete an existing Connect Application. + parameters: + - name: id + required: true + in: path + description: The application ID or client ID of the Connect Application. + schema: + type: string + example: conn_app_01HXYZ123456789ABCDEFGHIJ + 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 + tags: + - applications + /connect/applications/{id}/client_secrets: + get: + operationId: ApplicationCredentialsController_list + summary: List Client Secrets for a Connect Application + description: List all client secrets associated with a Connect Application. + parameters: + - name: id + required: true + in: path + description: The application ID or client ID of the Connect Application. + schema: + type: string + example: conn_app_01HXYZ123456789ABCDEFGHIJ + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the connect application secret object. + const: connect_application_secret + id: + type: string + description: The unique ID of the client secret. + example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q + secret_hint: + type: string + description: >- + A hint showing the last few characters of the secret + value. + example: abc123 + last_used_at: + type: + - string + - 'null' + description: >- + The timestamp when the client secret was last used, or + null if never used. + example: null + 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 + - secret_hint + - last_used_at + - created_at + - updated_at + '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 + tags: + - application.client-secrets + post: + operationId: ApplicationCredentialsController_create + summary: Create a new client secret for a Connect Application + description: Create new secrets for a Connect Application. + parameters: + - name: id + required: true + in: path + description: The application ID or client ID of the Connect Application. + schema: + type: string + example: conn_app_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateApplicationSecretDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/NewConnectApplicationSecret' + '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 + tags: + - application.client-secrets + /connect/client_secrets/{id}: + delete: + operationId: ApplicationCredentialsController_delete + summary: Delete a Client Secret + description: Delete (revoke) an existing client secret. + parameters: + - name: id + required: true + in: path + description: The unique ID of the client secret. + schema: + type: string + example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q + 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 + tags: + - application.client-secrets + /connections: + get: + operationId: ConnectionsController_list + summary: List Connections + description: >- + Get a list of all of your existing connections matching the criteria + specified. + 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. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: connection_type + required: false + in: query + description: Filter Connections by their type. + schema: + example: GithubOAuth + enum: + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - CloudflareSAML + - ClassLinkSAML + - CleverOIDC + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GithubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + type: string + - name: domain + required: false + in: query + description: Filter Connections by their associated domain. + schema: + example: foo-corp.com + type: string + - name: organization_id + required: false + in: query + description: Filter Connections by their associated organization. + schema: + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + type: string + - name: search + required: false + in: query + description: Searchable text to match against Connection names. + schema: + example: Foo Corp + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectionList' + '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 + '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 + tags: + - connections + /connections/{id}: + get: + operationId: ConnectionsController_find + summary: Get a Connection + description: Get the details of an existing connection. + parameters: + - name: id + required: true + in: path + description: Unique identifier for the Connection. + schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Connection' + '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 + tags: + - connections + delete: + operationId: ConnectionsController_delete + summary: Delete a Connection + description: Permanently deletes an existing connection. It cannot be undone. + parameters: + - name: id + required: true + in: path + description: Unique identifier for the Connection. + schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + '204': + description: No Content + '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 + tags: + - connections + /data-integrations/{slug}/authorize: + post: + operationId: DataIntegrationsController_getDataIntegrationAuthorizeUrl + summary: Get authorization URL + description: >- + Generates an OAuth authorization URL to initiate the connection flow for + a user. Redirect the user to the returned URL to begin the OAuth flow + with the third-party provider. + parameters: + - name: slug + required: true + in: path + description: >- + The slug identifier of the provider (e.g., `github`, `slack`, + `notion`). + schema: + example: github + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The ID of the user to authorize. + example: user_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: string + description: >- + An organization ID to scope the authorization to a specific + organization. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + return_to: + type: string + format: uri + description: The URL to redirect the user to after authorization. + example: https://example.com/callback + required: + - user_id + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DataIntegrationAuthorizeUrlResponse' + '400': + description: Bad Request + 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 + '401': + description: Unauthorized + '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 + tags: + - pipes + /data-integrations/{slug}/token: + post: + operationId: DataIntegrationsController_getUserlandUserToken + summary: Get an access token for a connected account + description: >- + Fetches a valid OAuth access token for a user's connected account. + WorkOS automatically handles token refresh, ensuring you always receive + a valid, non-expired token. + parameters: + - name: slug + required: true + in: path + description: The identifier of the integration. + schema: + example: github + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: A [User](/reference/authkit/user) identifier. + example: user_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: string + description: >- + An [Organization](/reference/organization) identifier. + Optional parameter to scope the connection to a specific + organization. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - user_id + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DataIntegrationAccessTokenResponse' + '400': + description: Bad Request + 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 + '401': + description: Unauthorized + '404': + description: Data integration not found for the given provider slug. + 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 + tags: + - pipes + /directories: + get: + operationId: DirectoriesController_list + summary: List Directories + description: >- + Get a list of all of your existing directories matching the criteria + specified. + 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. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization_id + required: false + in: query + description: Filter Directories by their associated organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: search + required: false + in: query + description: Searchable text to match against Directory names. + schema: + example: Foo Corp + type: string + - name: domain + required: false + in: query + description: Filter Directories by their associated domain. + deprecated: true + schema: + example: foo-corp.com + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DirectoryList' + '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 + '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 + tags: + - directories + /directories/{id}: + get: + operationId: DirectoriesController_find + summary: Get a Directory + description: Get the details of an existing directory. + parameters: + - name: id + required: true + in: path + description: Unique identifier for the Directory. + schema: + example: directory_01ECAZ4NV9QMV47GW873HDCX74 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Directory' + '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 + tags: + - directories + delete: + operationId: DirectoriesController_deleteDirectory + summary: Delete a Directory + description: Permanently deletes an existing directory. It cannot be undone. + parameters: + - name: id + required: true + in: path + description: Unique identifier for the Directory. + schema: + example: directory_01ECAZ4NV9QMV47GW873HDCX74 + type: string + responses: + '200': + description: OK + '202': + description: '' + content: + application/json: + schema: {} + '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 + tags: + - directories + /directory_groups: + get: + operationId: DirectoryGroupsController_list + summary: List Directory Groups + description: >- + Get a list of all of existing directory groups matching the criteria + specified. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - 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: user + required: false + in: query + description: >- + Unique identifier of the WorkOS Directory User. This value can be + obtained from the WorkOS API. + schema: + example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DirectoryGroupList' + '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 + tags: + - directory-groups + /directory_groups/{id}: + get: + operationId: DirectoryGroupsController_find + summary: Get a Directory Group + description: Get the details of an existing Directory Group. + parameters: + - name: id + required: true + in: path + description: Unique identifier for the Directory Group. + schema: + example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DirectoryGroup' + '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 + tags: + - directory-groups + /directory_users: + get: + operationId: DirectoryUsersController_list + summary: List Directory Users + description: >- + Get a list of all of existing Directory Users matching the criteria + specified. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - 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 + tags: + - directory-users + /directory_users/{id}: + get: + operationId: DirectoryUsersController_find + summary: Get a Directory User + description: Get the details of an existing Directory User. + 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 + tags: + - directory-users + /events: + get: + operationId: EventsController_list + summary: List events + description: List events for the current environment. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: events + required: false + in: query + description: >- + Filter events by one or more event types (e.g. + `dsync.user.created`). + style: form + explode: false + schema: + example: + - dsync.user.created + - dsync.user.updated + type: array + items: + type: string + - name: range_start + required: false + in: query + description: ISO-8601 date string to filter events created after this date. + schema: + example: '2025-01-01T00:00:00Z' + type: string + - name: range_end + required: false + in: query + description: ISO-8601 date string to filter events created before this date. + schema: + example: '2025-12-31T23:59:59Z' + type: string + - name: organization_id + required: false + in: query + description: >- + Filter events by the [Organization](/reference/organization) that + the event is associated with. + schema: + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/EventList' + '400': + description: Bad Request + 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: + 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: events + required: + - code + - field + description: The list of validation errors. + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - errors + - message + tags: + - events + /feature-flags: + get: + operationId: FeatureFlagsController_list + summary: List feature flags + description: >- + Get a list of all of your existing feature flags matching the criteria + specified. + 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. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FlagList' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - 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 + tags: + - feature-flags + /feature-flags/{slug}: + get: + operationId: FeatureFlagsController_findBySlug + summary: Get a feature flag + description: Get the details of an existing feature flag by its slug. + parameters: + - name: slug + required: true + in: path + description: A unique key to reference the Feature Flag. + schema: + type: string + example: advanced-analytics + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Flag' + '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 + tags: + - feature-flags + /feature-flags/{slug}/disable: + put: + operationId: FeatureFlagsController_disableFlag + summary: Disable a feature flag + description: Disables a feature flag in the current environment. + parameters: + - name: slug + required: true + in: path + description: A unique key to reference the Feature Flag. + schema: + type: string + example: advanced-analytics + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the Feature Flag object. + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: >- + A descriptive name for the Feature Flag. This field does + not need to be unique. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: >- + Labels assigned to the Feature Flag for categorizing and + filtering. + example: + - reports + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the + current environment. + example: false + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't + match any configured targeting rules. + example: false + 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 + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + x-inline-with-overrides: true + '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 + tags: + - feature-flags + /feature-flags/{slug}/enable: + put: + operationId: FeatureFlagsController_enableFlag + summary: Enable a feature flag + description: Enables a feature flag in the current environment. + parameters: + - name: slug + required: true + in: path + description: A unique key to reference the Feature Flag. + schema: + type: string + example: advanced-analytics + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the Feature Flag object. + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: >- + A descriptive name for the Feature Flag. This field does + not need to be unique. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: >- + Labels assigned to the Feature Flag for categorizing and + filtering. + example: + - reports + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the + current environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't + match any configured targeting rules. + example: false + 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 + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + x-inline-with-overrides: true + '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 + tags: + - feature-flags + /feature-flags/{slug}/targets/{resourceId}: + post: + operationId: FlagTargetsController_createTarget + summary: Add a feature flag target + description: >- + Enables a feature flag for a specific target in the current environment. + Currently, supported targets include users and organizations. + parameters: + - name: resourceId + required: true + in: path + description: The resource ID in format "user_" or "org_". + schema: + example: user_01234567890abcdef + type: string + - name: slug + required: true + in: path + description: The unique slug identifier of the feature flag. + schema: + example: beta-feature + type: string + responses: + '204': + description: Target created or updated successfully. + '400': + description: Invalid resourceId format. + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Invalid resource id + code: + type: string + description: The error code identifying the type of error. + example: invalid_resource_id_format + statusCode: + type: number + description: The HTTP status code. + example: 400 + '403': + description: Access denied. + 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: Feature flag, user, or organization 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 + tags: + - feature-flags.targets + delete: + operationId: FlagTargetsController_deleteTarget + summary: Remove a feature flag target + description: >- + Removes a target from the feature flag's target list in the current + environment. Currently, supported targets include users and + organizations. + parameters: + - name: resourceId + required: true + in: path + description: The resource ID in format "user_" or "org_". + schema: + example: user_01234567890abcdef + type: string + - name: slug + required: true + in: path + description: The unique slug identifier of the feature flag. + schema: + example: beta-feature + type: string + responses: + '204': + description: Target deleted successfully. + '400': + description: Invalid resourceId format. + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Invalid resource id + code: + type: string + description: The error code identifying the type of error. + example: invalid_resource_id_format + statusCode: + type: number + description: The HTTP status code. + example: 400 + '403': + description: Access denied. + 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: Feature flag, user, or organization 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 + tags: + - feature-flags.targets + /organization_domains: + post: + operationId: OrganizationDomainsController_create + summary: Create an Organization Domain + description: Creates a new Organization Domain. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateOrganizationDomainDto' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + x-inline-with-overrides: true + '409': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + const: domain_already_exists + message: + type: string + description: A human-readable description of the error. + example: Domain already exists for this organization. + required: + - code + - message + tags: + - organization-domains + /organization_domains/{id}: + get: + operationId: OrganizationDomainsController_get + summary: Get an Organization Domain + description: Get the details of an existing organization domain. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the organization domain. + schema: + type: string + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDomainStandAlone' + '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 + tags: + - organization-domains + delete: + operationId: OrganizationDomainsController_delete + summary: Delete an Organization Domain + description: Permanently deletes an organization domain. It cannot be undone. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the organization domain. + schema: + type: string + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + responses: + '204': + description: Organization domain deleted successfully. + '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 + tags: + - organization-domains + /organization_domains/{id}/verify: + post: + operationId: OrganizationDomainsController_verify + summary: Verify an Organization Domain + description: Initiates verification process for an Organization Domain. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the organization domain. + schema: + type: string + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDomainStandAlone' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + const: domain_already_verified + message: + type: string + description: A human-readable description of the error. + example: Domain is already verified. + required: + - code + - message + tags: + - organization-domains + /organizations: + get: + operationId: OrganizationsController_list + summary: List Organizations + description: >- + Get a list of all of your existing organizations matching the criteria + specified. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: domains + required: false + in: query + description: >- + The domains of an Organization. Any Organization with a matching + domain will be returned. + style: form + explode: false + schema: + type: array + items: + type: string + example: + - foo-corp.com + - name: search + required: false + in: query + description: >- + Searchable text for an Organization. Matches against the + organization name. + schema: + type: string + example: Acme Corp + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationList' + '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 + tags: + - organizations + post: + operationId: OrganizationsController_create + summary: Create an Organization + description: Creates a new organization in the current environment. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDto' + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + example: + object: organization + name: Foo Corp + domains: + - object: organization_domain + id: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: org_01HE8GSH8FQPASKSY27THRKRBP + domain: foo-corp.com + state: pending + verification_prefix: superapp-domain-verification-z3kjny + verification_token: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: dns + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + metadata: + tier: diamond + stripe_customer_id: cus_R9qWAGMQ6nGE7V + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + allow_profiles_outside_organization: false + id: org_01EHWNCE74X7JSDV0X3SZ3KJNY + external_id: ext_12345 + description: Created + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_metadata + const: invalid_metadata + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_id_already_used + const: external_id_already_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '409': + description: '' + 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 + tags: + - organizations + /organizations/external_id/{external_id}: + get: + operationId: OrganizationsController_getByExternalId + summary: Get an Organization by External ID + description: >- + Get the details of an existing organization by an [external + identifier](/authkit/metadata/external-identifiers). + parameters: + - name: external_id + required: true + in: path + description: The external ID of the Organization. + schema: + type: string + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + '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 + tags: + - organizations + /organizations/{id}: + get: + operationId: OrganizationsController_find + summary: Get an Organization + description: Get the details of an existing organization. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + '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 + tags: + - organizations + put: + operationId: OrganizationsController_updateOrganization + summary: Update an Organization + description: Updates an organization in the current environment. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationDto' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + example: + object: organization + name: Foo Corp + domains: + - object: organization_domain + id: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: org_01HE8GSH8FQPASKSY27THRKRBP + domain: foo-corp.com + state: pending + verification_prefix: superapp-domain-verification-z3kjny + verification_token: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: dns + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + metadata: + tier: diamond + stripe_customer_id: cus_R9qWAGMQ6nGE7V + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + allow_profiles_outside_organization: false + id: org_01EHZNVPK3SFK441A1RGBFSHRT + external_id: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + description: OK + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_metadata + const: invalid_metadata + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_id_already_used + const: external_id_already_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: stripe_customer_id_already_used + const: stripe_customer_id_already_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + '409': + description: '' + 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 + tags: + - organizations + delete: + operationId: OrganizationsController_deleteOrganization + summary: Delete an Organization + description: >- + Permanently deletes an organization in the current environment. It + cannot be undone. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '200': + description: OK + '202': + description: '' + '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 + tags: + - organizations + /organizations/{id}/audit_log_configuration: + get: + operationId: OrganizationsController_getAuditLogConfiguration + summary: Get Audit Log Configuration + description: >- + Get the unified view of audit log trail and stream configuration for an + organization. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogConfiguration' + '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 + tags: + - organizations + /organizations/{id}/audit_logs_retention: + get: + operationId: AuditLogsRetentionController_auditLogsRetention + summary: Get Retention + description: Get the configured event retention period for the given Organization. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogsRetentionJson' + '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 + tags: + - audit-logs + put: + operationId: AuditLogsRetentionController_updateAuditLogsRetention + summary: Set Retention + description: Set the event retention period for the given Organization. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAuditLogsRetentionDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuditLogsRetentionJson' + '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 + tags: + - audit-logs + /organizations/{organizationId}/api_keys: + get: + operationId: OrganizationApiKeysController_list + summary: List API keys for an organization + description: Get a list of all API keys for an organization. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationApiKeyList' + '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 + tags: + - organizations.api_keys + post: + operationId: OrganizationApiKeysController_create + summary: Create an API key for an organization + description: Create a new API key for an organization. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateOrganizationApiKeyDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationApiKeyWithValue' + '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: 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 + tags: + - organizations.api_keys + /organizations/{organizationId}/feature-flags: + get: + operationId: OrganizationFeatureFlagsController_list + summary: List enabled feature flags for an organization + description: Get a list of all enabled feature flags for an organization. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FlagList' + '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 + tags: + - organizations.feature-flags + /organizations/{organizationId}/groups: + post: + operationId: GroupsController_create + summary: Create a group + description: Create a new group within an organization. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateGroupDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/Group' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + get: + operationId: GroupsController_list + summary: List groups + description: Get a paginated list of groups within an organization. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GroupList' + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + /organizations/{organizationId}/groups/{groupId}: + get: + operationId: GroupsController_get + summary: Get a group + description: Retrieve a group by its ID within an organization. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: groupId + required: true + in: path + description: The ID of the group. + schema: + type: string + example: group_01HXYZ123456789ABCDEFGHIJ + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Group' + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + patch: + operationId: GroupsController_update + summary: Update a group + description: >- + Update an existing group. Only the fields provided in the request body + will be updated. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: groupId + required: true + in: path + description: The ID of the group. + schema: + type: string + example: group_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateGroupDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Group' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: bad_request + const: bad_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + delete: + operationId: GroupsController_delete + summary: Delete a group + description: Delete a group from an organization. + parameters: + - name: organizationId + required: true + in: path + description: The ID of the organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: groupId + required: true + in: path + description: The ID of the group. + schema: + type: string + example: group_01HXYZ123456789ABCDEFGHIJ + responses: + '204': + description: No Content + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + /organizations/{organizationId}/groups/{groupId}/organization-memberships: + post: + operationId: GroupMembershipsController_addMember + summary: Add a member to a Group + description: Add an organization membership to a group. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: groupId + required: true + in: path + description: Unique identifier of the Group. + schema: + type: string + example: group_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateGroupMembershipDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Group' + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + get: + operationId: GroupMembershipsController_listMembers + summary: List Group members + description: Get a list of organization memberships in a group. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: groupId + required: true + in: path + description: Unique identifier of the Group. + schema: + type: string + example: group_01HXYZ123456789ABCDEFGHIJ + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseList + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + /organizations/{organizationId}/groups/{groupId}/organization-memberships/{omId}: + delete: + operationId: GroupMembershipsController_removeMember + summary: Remove a member from a Group + description: Remove an organization membership from a group. + parameters: + - name: organizationId + required: true + in: path + description: Unique identifier of the Organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: groupId + required: true + in: path + description: Unique identifier of the Group. + schema: + type: string + example: group_01HXYZ123456789ABCDEFGHIJ + - name: omId + required: true + in: path + description: Unique identifier of the Organization Membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + responses: + '204': + description: No Content + '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 + tags: + - groups + x-feature-flag: user-groups-enabled + /portal/generate_link: + post: + operationId: PortalSessionsController_create + summary: Generate a Portal Link + description: Generate a Portal Link scoped to an Organization. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GenerateLinkDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/PortalLinkResponse' + '400': + description: Bad Request + 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 + '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 + tags: + - admin-portal + /radar/attempts: + post: + operationId: RadarStandaloneController_assess + summary: Create an attempt + description: Assess a request for risk using the Radar engine and receive a verdict. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ip_address: + type: string + description: The IP address of the request to assess. + example: 49.78.240.97 + user_agent: + type: string + description: The user agent string of the request to assess. + example: Mozilla/5.0 + email: + type: string + format: email + description: The email address of the user making the request. + example: user@example.com + auth_method: + type: string + enum: + - Password + - Passkey + - Authenticator + - SMS_OTP + - Email_OTP + - Social + - SSO + - Other + description: The authentication method being used. + example: Password + action: + type: string + enum: + - login + - signup + - sign-up + - sign-in + - sign_up + - sign_in + - sign in + - sign up + description: The action being performed. + example: login + device_fingerprint: + type: string + description: An optional device fingerprint for the request. + example: fp_abc123 + bot_score: + type: string + description: An optional bot detection score for the request. + example: '0.1' + required: + - ip_address + - user_agent + - email + - auth_method + - action + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RadarStandaloneResponse' + '400': + description: Standalone radar is not enabled. + 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 + tags: + - radar + /radar/attempts/{id}: + put: + operationId: RadarStandaloneController_updateRadarAttempt + summary: Update a Radar attempt + description: >- + You may optionally inform Radar that an authentication attempt or + challenge was successful using this endpoint. Some Radar controls depend + on tracking recent successful attempts, such as impossible travel. + parameters: + - name: id + required: true + in: path + description: The unique identifier of the Radar attempt to update. + schema: + example: radar_att_01HZBC6N1EB1ZY7KG32X + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + challenge_status: + type: string + description: Set to `"success"` to mark the challenge as completed. + example: success + const: success + attempt_status: + type: string + description: >- + Set to `"success"` to mark the authentication attempt as + successful. + example: success + const: success + responses: + '204': + description: Radar attempt updated. + '400': + description: Bad Request + 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 + tags: + - radar + /radar/lists/{type}/{action}: + post: + operationId: RadarStandaloneController_updateRadarList + summary: Add an entry to a Radar list + description: Add an entry to a Radar list. + parameters: + - name: type + required: true + in: path + description: The type of the Radar list (e.g. ip_address, domain, email). + schema: + type: string + enum: + - ip_address + - domain + - email + - device + - user_agent + - device_fingerprint + - country + example: ip_address + - name: action + required: true + in: path + description: >- + The list action indicating whether to add the entry to the allow or + block list. + schema: + type: string + enum: + - block + - allow + example: block + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + entry: + type: string + description: >- + The value to add to the list. Must match the format of the + list type (e.g. a valid IP address for `ip_address`, a valid + email for `email`). + example: 198.51.100.42 + required: + - entry + responses: + '200': + description: Entry already present in the list. + content: + application/json: + schema: + $ref: '#/components/schemas/RadarListEntryAlreadyPresentResponse' + '201': + description: Created + '204': + description: Entry successfully added to the list. + '400': + description: Bad Request + 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 + tags: + - radar + delete: + operationId: RadarStandaloneController_deleteRadarListEntry + summary: Remove an entry from a Radar list + description: Remove an entry from a Radar list. + parameters: + - name: type + required: true + in: path + description: The type of the Radar list (e.g. ip_address, domain, email). + schema: + type: string + enum: + - ip_address + - domain + - email + - device + - user_agent + - device_fingerprint + - country + example: ip_address + - name: action + required: true + in: path + description: >- + The list action indicating whether to remove the entry from the + allow or block list. + schema: + type: string + enum: + - block + - allow + example: block + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + entry: + type: string + description: >- + The value to remove from the list. Must match an existing + entry. + example: 198.51.100.42 + required: + - entry + responses: + '204': + description: Radar list updated. + '400': + description: Bad Request + 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 + tags: + - radar + /sso/authorize: + get: + operationId: SsoController_authorize + summary: Initiate SSO + description: Initiates the single sign-on flow. + security: [] + parameters: + - name: provider_scopes + required: false + in: query + description: >- + Additional scopes to request from the identity provider. Applicable + when using OAuth or OpenID Connect connections. + style: form + explode: false + schema: + type: array + items: + type: string + example: + - openid + - profile + - email + - name: provider_query_params + required: false + in: query + description: >- + Key/value pairs of query parameters to pass to the OAuth provider. + Only applicable when using OAuth connections. + schema: + additionalProperties: + type: string + example: + hd: example.com + access_type: offline + type: object + - name: client_id + required: true + in: query + schema: + type: string + example: client_01HZBC6N1EB1ZY7KG32X + description: The unique identifier of the WorkOS environment client. + - name: domain + required: false + in: query + deprecated: true + schema: + type: string + example: example.com + description: >- + Deprecated. Use `connection` or `organization` instead. Used to + initiate SSO for a connection by domain. The domain must be + associated with a connection in your WorkOS environment. + - name: provider + required: false + in: query + schema: + type: string + enum: + - AppleOAuth + - BitbucketOAuth + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - IntuitOAuth + - LinkedInOAuth + - MicrosoftOAuth + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - XeroOAuth + example: GoogleOAuth + description: Used to initiate OAuth authentication with various providers. + - name: redirect_uri + required: true + in: query + schema: + type: string + format: uri + example: https://example.com/callback + description: >- + Where to redirect the user after they complete the authentication + process. You must use one of the redirect URIs configured via the + [Redirects](https://dashboard.workos.com/redirects) page on the + dashboard. + - name: response_type + required: true + in: query + schema: + type: string + example: code + const: code + description: >- + The only valid option for the response type parameter is `"code"`. + + + The `"code"` parameter value initiates an [authorization code grant + type](https://tools.ietf.org/html/rfc6749#section-4.1). This grant + type allows you to exchange an authorization code for an access + token during the redirect that takes place after a user has + authenticated with an identity provider. + - name: state + required: false + in: query + schema: + type: string + example: dj1kUXc0dzlXZ1hjUQ== + description: >- + An optional parameter that can be used to encode arbitrary + information to help restore application state between redirects. If + included, the redirect URI received from WorkOS will contain the + exact `state` that was passed. + - name: connection + required: false + in: query + schema: + type: string + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + description: >- + Used to initiate SSO for a connection. The value should be a WorkOS + connection ID. + + + You can persist the WorkOS connection ID with application user or + team identifiers. WorkOS will use the connection indicated by the + connection parameter to direct the user to the corresponding IdP for + authentication. + - name: organization + required: false + in: query + schema: + type: string + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + description: >- + Used to initiate SSO for an organization. The value should be a + WorkOS organization ID. + + + You can persist the WorkOS organization ID with application user or + team identifiers. WorkOS will use the organization ID to determine + the appropriate connection and the IdP to direct the user to for + authentication. + - name: domain_hint + required: false + in: query + schema: + type: string + example: example.com + description: >- + Can be used to pre-fill the domain field when initiating + authentication with Microsoft OAuth or with a Google SAML connection + type. + - name: login_hint + required: false + in: query + schema: + type: string + example: user@example.com + description: >- + Can be used to pre-fill the username/email address field of the IdP + sign-in page for the user, if you know their username ahead of time. + Currently supported for OAuth, OpenID Connect, Okta, and Entra ID + connections. + - name: nonce + required: false + in: query + schema: + type: string + example: abc123def456 + description: >- + A random string generated by the client that is used to mitigate + replay attacks. + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SsoAuthorizeUrlResponse' + '302': + headers: + Location: + schema: + type: string + format: uri + description: '' + tags: + - sso + /sso/jwks/{clientId}: + get: + operationId: SsoController_jsonWebKeySet + summary: Get JWKS + description: >- + Returns the JSON Web Key Set (JWKS) containing the public keys used for + verifying access tokens. + parameters: + - name: clientId + required: true + in: path + description: >- + Identifies the application making the request to the WorkOS server. + You can obtain your client ID from the [API + Keys](https://dashboard.workos.com/api-keys) page in the dashboard. + schema: + type: string + example: client_01HXYZ123456789ABCDEFGHIJ + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/JwksResponse' + '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 + tags: + - user-management.session-tokens + /sso/logout: + get: + operationId: SsoController_logout + summary: Logout Redirect + servers: + - url: https://auth.workos.com + description: >- + Logout allows to sign out a user from your application by triggering the + identity provider sign out flow. This `GET` endpoint should be a + redirection, since the identity provider user will be identified in the + browser session. + + + Before redirecting to this endpoint, you need to generate a short-lived + logout token using the [Logout + Authorize](/reference/sso/logout/authorize) endpoint. + security: [] + parameters: + - name: token + required: true + in: query + description: >- + The logout token returned from the [Logout + Authorize](/reference/sso/logout/authorize) endpoint. + schema: + type: string + example: >- + eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 + responses: + '200': + description: OK + '302': + headers: + Location: + schema: + type: string + format: uri + description: '' + '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 + tags: + - sso + /sso/logout/authorize: + post: + operationId: SsoController_logoutAuthorize + summary: Logout Authorize + servers: + - url: https://auth.workos.com + description: >- + You should call this endpoint from your server to generate a logout + token which is required for the [Logout Redirect](/reference/sso/logout) + endpoint. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + profile_id: + type: string + description: The unique ID of the profile to log out. + example: prof_01HXYZ123456789ABCDEFGHIJ + required: + - profile_id + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SsoLogoutAuthorizeResponse' + '201': + description: Created + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + error: + type: string + const: connection_invalid + error_description: + type: string + description: A human-readable description of the error. + example: >- + Single Logout is only supported for GenericOIDC + connections. + required: + - error + - error_description + - type: object + properties: + error: + type: string + const: unauthorized_client + error_description: + type: string + description: A human-readable description of the error. + example: Unauthorized + required: + - error + - error_description + '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 + tags: + - sso + /sso/profile: + get: + operationId: SsoController_getProfile + summary: Get a User Profile + security: + - access_token: [] + description: >- + Exchange an access token for a user's [Profile](/reference/sso/profile). + Because this profile is returned in the [Get a Profile and Token + endpoint](/reference/sso/profile/get-profile-and-token) your application + usually does not need to call this endpoint. It is available for any + authentication flows that require an additional endpoint to retrieve a + user's profile. + parameters: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Profile' + '401': + description: Unauthorized + content: + application/json: + schema: + type: object + properties: + error: + type: string + const: Unauthorized + required: + - error + '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 + tags: + - sso + /sso/token: + post: + operationId: SsoController_token + summary: Get a Profile and Token + description: >- + Get an access token along with the user + [Profile](/reference/sso/profile) using the code passed to your + [Redirect URI](/reference/sso/get-authorization-url/redirect-uri). + security: [] + parameters: + - name: client_id + required: true + in: query + description: The client ID of the WorkOS environment. + schema: + example: client_01HZBC6N1EB1ZY7KG32X + type: string + - name: client_secret + required: true + in: query + description: The client secret of the WorkOS environment. + schema: + example: sk_example_123456789 + type: string + - name: code + required: true + in: query + description: The authorization code received from the authorization callback. + schema: + example: authorization_code_value + type: string + - name: grant_type + required: true + in: query + description: The grant type for the token request. + schema: + example: authorization_code + type: string + const: authorization_code + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TokenQueryDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SsoTokenResponse' + '201': + description: Created + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + error: + type: string + const: invalid_client + error_description: + type: string + description: A human-readable description of the error. + example: Invalid client ID or secret. + required: + - error + - error_description + - type: object + properties: + error: + type: string + const: unauthorized_client + error_description: + type: string + description: A human-readable description of the error. + example: The client is not authorized to use this grant type. + required: + - error + - error_description + - type: object + properties: + error: + type: string + const: invalid_grant + error_description: + type: string + description: A human-readable description of the error. + example: The code has expired or has already been used. + required: + - error + - error_description + - type: object + properties: + error: + type: string + const: unsupported_grant_type + error_description: + type: string + description: A human-readable description of the error. + example: The grant type is not supported. + required: + - error + - error_description + '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 + tags: + - sso + /user_management/authenticate: + post: + operationId: UserlandSessionsController_authenticate + summary: Authenticate + description: >- + Authenticate a user with a specified [authentication + method](/reference/authkit/authentication). + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + oneOf: + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: authorization_code + code: + type: string + description: The authorization code received from the redirect. + example: vBqZKaPpsnJlPfXiDqN7b6VTz + code_verifier: + type: string + description: >- + The PKCE code verifier used to derive the code challenge + passed to the authorization URL. + example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk + invitation_token: + type: string + description: An invitation token to accept during authentication. + example: inv_tok_01HXYZ123456789ABCDEFGHIJ + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - code + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: password + email: + type: string + description: The user's email address. + example: user@example.com + password: + type: string + description: The user's password. + example: strong_password_123! + invitation_token: + type: string + description: An invitation token to accept during authentication. + example: inv_tok_01HXYZ123456789ABCDEFGHIJ + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - email + - password + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: refresh_token + refresh_token: + type: string + description: The refresh token to exchange for new tokens. + example: yAjhKk23hJMM3DaR... + organization_id: + type: string + description: The ID of the organization to scope the session to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - refresh_token + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: urn:workos:oauth:grant-type:magic-auth:code + code: + type: string + description: The one-time code for Magic Auth authentication. + example: '123456' + email: + type: string + description: The user's email address. + example: user@example.com + invitation_token: + type: string + description: An invitation token to accept during authentication. + example: inv_tok_01HXYZ123456789ABCDEFGHIJ + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - code + - email + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: urn:workos:oauth:grant-type:email-verification:code + code: + type: string + description: The email verification code. + example: '123456' + pending_authentication_token: + type: string + description: >- + The pending authentication token from a previous + authentication attempt. + example: cTDQJTTkTkkVYxbn... + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - code + - pending_authentication_token + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: urn:workos:oauth:grant-type:mfa-totp + code: + type: string + description: The TOTP code from the authenticator app. + example: '123456' + pending_authentication_token: + type: string + description: >- + The pending authentication token from a previous + authentication attempt. + example: cTDQJTTkTkkVYxbn... + authentication_challenge_id: + type: string + description: The ID of the MFA authentication challenge. + example: auth_challenge_01HXYZ123456789ABCDEFGHIJ + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - code + - pending_authentication_token + - authentication_challenge_id + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + client_secret: + type: string + description: The client secret of the application. + example: sk_test_.... + grant_type: + type: string + const: urn:workos:oauth:grant-type:organization-selection + pending_authentication_token: + type: string + description: >- + The pending authentication token from a previous + authentication attempt. + example: cTDQJTTkTkkVYxbn... + organization_id: + type: string + description: The ID of the organization the user selected. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - client_secret + - grant_type + - pending_authentication_token + - organization_id + - type: object + properties: + client_id: + type: string + description: The client ID of the application. + example: client_01HXYZ123456789ABCDEFGHIJ + grant_type: + type: string + const: urn:ietf:params:oauth:grant-type:device_code + device_code: + type: string + description: The device verification code. + example: Ao4fMrDS... + ip_address: + type: string + description: The IP address of the user's request. + example: 203.0.113.42 + device_id: + type: string + description: A unique identifier for the device. + example: device_01HXYZ123456789ABCDEFGHIJ + user_agent: + type: string + description: The user agent string from the user's browser. + example: Mozilla/5.0 + required: + - client_id + - grant_type + - device_code + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandAuthenticateResponse' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_organization_id + const: invalid_organization_id + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: code_challenge_not_found + const: code_challenge_not_found + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_credentials + const: invalid_credentials + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_one_time_code + const: invalid_one_time_code + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: one_time_code_previously_used + const: one_time_code_previously_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: one_time_code_expired + const: one_time_code_expired + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: one_time_code_too_many_attempts + const: one_time_code_too_many_attempts + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_pending_authentication_token + const: invalid_pending_authentication_token + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: user_mismatch + const: user_mismatch + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invalid_client + const: invalid_client + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invalid_client.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: unauthorized_client + const: unauthorized_client + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: unauthorized_client.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invalid_profile + const: invalid_profile + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invalid_profile.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invitation_invalid + const: invitation_invalid + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invitation_invalid.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invitation_cannot_be_used_for_email + const: invitation_cannot_be_used_for_email + error_description: + type: string + description: A human-readable description of the error. + example: >- + The request failed due to: + invitation_cannot_be_used_for_email. + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: authentication_method_not_allowed + const: authentication_method_not_allowed + error_description: + type: string + description: A human-readable description of the error. + example: >- + The request failed due to: + authentication_method_not_allowed. + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invalid_connection + const: invalid_connection + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invalid_connection.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: sign_up_not_allowed + const: sign_up_not_allowed + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: sign_up_not_allowed.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: organization_authentication_methods_required + const: organization_authentication_methods_required + error_description: + type: string + description: A human-readable description of the error. + example: >- + The request failed due to: + organization_authentication_methods_required. + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invalid_link_authorization_code + const: invalid_link_authorization_code + error_description: + type: string + description: A human-readable description of the error. + example: >- + The request failed due to: + invalid_link_authorization_code. + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: extra_attributes_required + const: extra_attributes_required + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: extra_attributes_required.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: pkce_not_supported + const: pkce_not_supported + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: pkce_not_supported.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: expired_token + const: expired_token + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: expired_token.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: authorization_pending + const: authorization_pending + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: authorization_pending.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: access_denied + const: access_denied + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: access_denied.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: slow_down + const: slow_down + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: slow_down.' + required: + - error + - error_description + - type: object + properties: + message: + type: string + const: Must use SSO for selected organization + required: + - message + - oneOf: + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invalid_grant + const: invalid_grant + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invalid_grant.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invalid_request + const: invalid_request + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invalid_request.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: organization_not_found + const: organization_not_found + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: organization_not_found.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: organization_membership_not_found + const: organization_membership_not_found + error_description: + type: string + description: A human-readable description of the error. + example: >- + The request failed due to: + organization_membership_not_found. + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: mfa_enrollment + const: mfa_enrollment + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: mfa_enrollment.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: token_too_big + const: token_too_big + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: token_too_big.' + required: + - error + - error_description + - allOf: + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: sso_required + const: sso_required + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: sso_required.' + required: + - error + - error_description + - type: object + properties: + connection_ids: + type: array + items: + type: string + example: conn_01FVYZ... + description: >- + The IDs of the SSO connections the user must + authenticate through. + email: + type: string + description: >- + The email address of the user that must + authenticate via SSO. + example: user@example.com + required: + - connection_ids + - email + '403': + description: Forbidden + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: mfa_enrollment + const: mfa_enrollment + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: mfa_challenge + const: mfa_challenge + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: authentication_method_not_allowed + const: authentication_method_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_verification_required + const: email_verification_required + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_password_auth_disabled + const: email_password_auth_disabled + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: organization_selection_required + const: organization_selection_required + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: passkey_progressive_enrollment + const: passkey_progressive_enrollment + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: radar_challenge + const: radar_challenge + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: radar_sign_up_challenge + const: radar_sign_up_challenge + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: application_consent_required + const: application_consent_required + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - user-management.authentication + /user_management/authorize: + get: + operationId: UserlandSsoController_authorize + summary: Get an authorization URL + description: >- + Generates an OAuth 2.0 authorization URL to authenticate a user with + AuthKit or SSO. + security: [] + parameters: + - name: code_challenge_method + required: false + in: query + schema: + type: string + example: S256 + const: S256 + description: >- + The only valid PKCE code challenge method is `"S256"`. Required when + specifying a `code_challenge`. + - name: code_challenge + required: false + in: query + schema: + type: string + example: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM + description: >- + Code challenge derived from the code verifier used for the PKCE + flow. + - name: domain_hint + required: false + in: query + schema: + type: string + example: example.com + description: A domain hint for SSO connection lookup. + - name: connection_id + required: false + in: query + schema: + type: string + example: conn_01EHQMYV6MBK39QC5PZXHY59C3 + description: The ID of an SSO connection to use for authentication. + - name: provider_query_params + required: false + in: query + schema: + type: object + additionalProperties: + type: string + example: + hd: example.com + access_type: offline + description: Key/value pairs of query parameters to pass to the OAuth provider. + - name: provider_scopes + required: false + in: query + style: form + explode: false + schema: + type: array + items: + type: string + example: + - openid + - profile + - email + description: Additional OAuth scopes to request from the identity provider. + - name: invitation_token + required: false + in: query + schema: + type: string + example: inv_token_abc123 + description: >- + A token representing a user invitation to redeem during + authentication. + - name: screen_hint + required: false + in: query + schema: + type: string + enum: + - sign-up + - sign-in + default: sign-in + example: sign-in + description: >- + Used to specify which screen to display when the provider is + `authkit`. + - name: login_hint + required: false + in: query + schema: + type: string + example: user@example.com + description: >- + A hint to the authorization server about the login identifier the + user might use. + - name: provider + required: false + in: query + schema: + type: string + enum: + - authkit + - AppleOAuth + - BitbucketOAuth + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - IntuitOAuth + - LinkedInOAuth + - MicrosoftOAuth + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - XeroOAuth + example: GoogleOAuth + description: >- + The OAuth provider to authenticate with (e.g., GoogleOAuth, + MicrosoftOAuth, GitHubOAuth). + - name: prompt + required: false + in: query + schema: + type: string + example: login + description: Controls the authentication flow behavior for the user. + - name: state + required: false + in: query + schema: + type: string + example: eyJyZXR1cm5UbyI6ICIvZGFzaGJvYXJkIn0= + description: >- + An opaque value used to maintain state between the request and the + callback. + - name: organization_id + required: false + in: query + schema: + type: string + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + description: The ID of the organization to authenticate the user against. + - name: response_type + required: true + in: query + schema: + type: string + example: code + const: code + description: The response type of the application. + - name: redirect_uri + required: true + in: query + schema: + type: string + format: uri + example: https://example.com/callback + description: >- + The callback URI where the authorization code will be sent after + authentication. + - name: client_id + required: true + in: query + schema: + type: string + example: client_01HZBC6N1EB1ZY7KG32X + description: The unique identifier of the WorkOS environment client. + responses: + '200': + headers: + location: + schema: + type: string + format: uri + description: OK + '302': + headers: + location: + schema: + type: string + format: uri + description: '' + tags: + - user-management.authentication + /user_management/authorize/device: + post: + operationId: UserlandSsoController_deviceAuthorization + summary: Get device authorization URL + description: >- + Initiates the CLI Auth flow by requesting a device code and verification + URLs. This endpoint implements the OAuth 2.0 Device Authorization Flow + ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) and is + designed for command-line applications or other devices with limited + input capabilities. + security: [] + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + client_id: + type: string + description: The WorkOS client ID for your application. + example: client_01HZBC6N1EB1ZY7KG32X + required: + - client_id + responses: + '200': + description: Device authorization response with codes and verification URI. + content: + application/json: + schema: + $ref: '#/components/schemas/DeviceAuthorizationResponse' + '400': + description: Invalid request parameters. + content: + application/json: + schema: + type: object + properties: + error: + type: string + description: Error code. + example: invalid_client + error_description: + type: string + description: Human-readable error description. + example: Unknown client + required: + - error + - error_description + '403': + description: Feature not enabled for team. + content: + application/json: + schema: + type: object + properties: + error: + type: string + description: Error code. + example: access_denied + error_description: + type: string + description: Human-readable error description. + example: Device authorization grant is not enabled for this team + required: + - error + - error_description + tags: + - user-management.authentication + /user_management/cors_origins: + post: + operationId: CorsOriginsController_createCorsOrigin + summary: Create a CORS origin + description: >- + Creates a new CORS origin for the current environment. CORS origins + allow browser-based applications to make requests to the WorkOS API. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCorsOriginDto' + responses: + '201': + description: CORS origin created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/CorsOriginResponse' + '409': + description: Duplicate CORS origin. + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code. + example: duplicate_cors_origin + message: + type: string + description: A human-readable error message. + example: CORS origin already exists. + '422': + description: Validation error. + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable error message. + example: Validation failed. + errors: + type: array + description: The list of validation errors. + items: + type: object + properties: + property: + type: string + description: The property that failed validation. + example: origin + constraints: + type: object + tags: + - user-management.cors-origins + /user_management/email_verification/{id}: + get: + operationId: UserlandUsersController_getEmailVerification + summary: Get an email verification code + description: >- + Get the details of an existing email verification code that can be used + to send an email to a user for verification. + parameters: + - name: id + required: true + in: path + description: The ID of the email verification code. + schema: + type: string + example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/EmailVerification' + '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 + tags: + - user-management.users + /user_management/invitations: + get: + operationId: UserlandUserInvitesController_list + summary: List invitations + description: Get a list of all of invitations matching the criteria specified. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization_id + required: false + in: query + description: >- + The ID of the [organization](/reference/organization) that the + recipient will join. + schema: + example: org_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - name: email + required: false + in: query + description: The email address of the recipient. + schema: + example: marcelina.davis@example.com + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + 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: invitation_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: invitation_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: + type: array + description: The list of records for the current page. + items: + $ref: '#/components/schemas/UserlandUserInvite' + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.invitations + post: + operationId: UserlandUserInvitesController_create + summary: Send an invitation + description: Sends an invitation email to the recipient. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserlandUserInviteOptionsDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_already_invited_to_organization + const: email_already_invited_to_organization + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: user_already_organization_member + const: user_already_organization_member + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_already_invited + const: email_already_invited + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: user_already_exists + const: user_already_exists + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: expires_in_days_too_short + const: expires_in_days_too_short + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: expires_in_days_too_long + const: expires_in_days_too_long + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_role + const: invalid_role + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.invitations + x-sends-email: true + /user_management/invitations/by_token/{token}: + get: + operationId: UserlandUserInvitesController_getByToken + summary: Find an invitation by token + description: Retrieve an existing invitation using the token. + parameters: + - name: token + required: true + in: path + description: The token used to accept the invitation. + schema: + example: Z1uX3RbwcIl5fIGJJJCXXisdI + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' + '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 + tags: + - user-management.invitations + /user_management/invitations/{id}: + get: + operationId: UserlandUserInvitesController_get + summary: Get an invitation + description: Get the details of an existing invitation. + parameters: + - name: id + required: true + in: path + description: The unique ID of the invitation. + schema: + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' + '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 + tags: + - user-management.invitations + /user_management/invitations/{id}/accept: + post: + operationId: UserlandUserInvitesController_accept + summary: Accept an invitation + description: >- + Accepts an invitation and, if linked to an organization, activates the + user's membership in that organization. + parameters: + - name: id + required: true + in: path + description: The unique ID of the invitation. + schema: + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: accepted + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null if + not yet accepted. + example: '2026-01-15T12:00:00.000Z' + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null if + not revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) that + the recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: The ID of the user who invited the recipient, if provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who accepted the invitation, once + accepted. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on + acceptance. Reflects the current role on the invitee's + organization membership. null when the invitation has no + associated organization. + example: admin + 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' + token: + type: string + description: The token used to accept the invitation. + example: Z1uX3RbwcIl5fIGJJJCXXisdI + accept_invitation_url: + type: string + description: The URL where the recipient can accept the invitation. + example: >- + https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI + required: + - object + - id + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + - token + - accept_invitation_url + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + enum: + - invite_not_pending + - invalid_invite + - invite_has_accepted_user_id + message: + type: string + description: A human-readable description of the error. + example: Invite is not pending. + required: + - code + - 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 + tags: + - user-management.invitations + /user_management/invitations/{id}/resend: + post: + operationId: UserlandUserInvitesController_resend + summary: Resend an invitation + description: >- + Resends an invitation email to the recipient. The invitation must be in + a pending state. + parameters: + - name: id + required: true + in: path + description: The unique ID of the invitation. + schema: + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ResendUserlandUserInviteOptionsDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserInvite' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + const: invite_expired + message: + type: string + description: A human-readable description of the error. + example: Invite has expired. + required: + - code + - message + - type: object + properties: + code: + type: string + const: invite_revoked + message: + type: string + description: A human-readable description of the error. + example: Invite has been revoked. + required: + - code + - message + - type: object + properties: + code: + type: string + const: invite_accepted + message: + type: string + description: A human-readable description of the error. + example: Invite has already been accepted. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.invitations + x-sends-email: true + /user_management/invitations/{id}/revoke: + post: + operationId: UserlandUserInvitesController_revoke + summary: Revoke an invitation + description: Revokes an existing invitation. + parameters: + - name: id + required: true + in: path + description: The unique ID of the invitation. + schema: + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: revoked + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null if + not yet accepted. + example: null + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null if + not revoked. + example: '2026-01-15T12:00:00.000Z' + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) that + the recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: The ID of the user who invited the recipient, if provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who accepted the invitation, once + accepted. + example: null + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on + acceptance. Reflects the current role on the invitee's + organization membership. null when the invitation has no + associated organization. + example: admin + 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' + token: + type: string + description: The token used to accept the invitation. + example: Z1uX3RbwcIl5fIGJJJCXXisdI + accept_invitation_url: + type: string + description: The URL where the recipient can accept the invitation. + example: >- + https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI + required: + - object + - id + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + - token + - accept_invitation_url + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invite_not_pending + const: invite_not_pending + message: + type: string + description: A human-readable description of the error. + example: Invite is not pending. + required: + - code + - message + tags: + - user-management.invitations + /user_management/jwt_template: + get: + operationId: JwtTemplatesController_getJwtTemplate + summary: Get JWT template + description: Get the JWT template for the current environment. + parameters: [] + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/JwtTemplate' + '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 + tags: + - user-management.jwt-template + put: + operationId: JwtTemplatesController_updateJwtTemplate + summary: Update JWT template + description: Update the JWT template for the current environment. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateJwtTemplateDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/JwtTemplate' + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.jwt-template + /user_management/magic_auth: + post: + operationId: UserlandMagicAuthController_sendMagicAuthCodeAndReturn + summary: Create a Magic Auth code + description: >- + Creates a one-time authentication code that can be sent to the user's + email address. The code expires in 10 minutes. To verify the code, + [authenticate the user with Magic + Auth](/reference/authkit/authentication/magic-auth). + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserlandMagicCodeAndReturnDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/MagicAuth' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: invitation_invalid + const: invitation_invalid + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: invitation_invalid.' + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: authentication_method_not_allowed + const: authentication_method_not_allowed + error_description: + type: string + description: A human-readable description of the error. + example: >- + The request failed due to: + authentication_method_not_allowed. + required: + - error + - error_description + - type: object + properties: + error: + type: string + description: The OAuth error code. + example: sign_up_not_allowed + const: sign_up_not_allowed + error_description: + type: string + description: A human-readable description of the error. + example: 'The request failed due to: sign_up_not_allowed.' + required: + - error + - error_description + '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: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - user-management.magic-auth + x-sends-email: true + /user_management/magic_auth/{id}: + get: + operationId: UserlandMagicAuthController_get + summary: Get Magic Auth code details + description: >- + Get the details of an existing [Magic + Auth](/reference/authkit/magic-auth) code that can be used to send an + email to a user for authentication. + parameters: + - name: id + required: true + in: path + description: The unique ID of the Magic Auth code. + schema: + example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/MagicAuth' + '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 + tags: + - user-management.magic-auth + /user_management/organization_memberships: + get: + operationId: UserlandUserOrganizationMembershipsController_list + summary: List organization memberships + description: >- + Get a list of all organization memberships matching the criteria + specified. At least one of `user_id` or `organization_id` must be + provided. By default only active memberships are returned. Use the + `statuses` parameter to filter by other statuses. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization_id + required: false + in: query + description: >- + The ID of the [organization](/reference/organization) which the user + belongs to. + schema: + example: org_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - name: statuses + required: false + in: query + description: >- + Filter by the status of the organization membership. Array including + any of `active`, `inactive`, or `pending`. + style: form + explode: false + schema: + example: + - active + type: array + items: + type: string + enum: + - active + - inactive + - pending + - name: user_id + required: false + in: query + description: The ID of the [user](/reference/authkit/user). + schema: + example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + 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: om_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: om_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: + type: array + description: The list of records for the current page. + items: + $ref: >- + #/components/schemas/UserlandUserOrganizationMembership + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: missing_user_id_or_organization_id + const: missing_user_id_or_organization_id + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + tags: + - user-management.organization-membership + post: + operationId: UserlandUserOrganizationMembershipsController_create + summary: Create an organization membership + description: >- + Creates a new `active` organization membership for the given + organization and user. + + + Calling this API with an organization and user that match an `inactive` + organization membership will activate the membership with the specified + role(s). + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserlandUserOrganizationMembershipDto' + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of + `active`, `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a + directory sync connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the + linked [Directory + User](/reference/directory-sync/directory-user) or [SSO + Profile](/reference/sso/profile). Directory User + attributes take precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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' + role: + $ref: '#/components/schemas/SlimRole' + description: >- + The primary role assigned to the user within the + organization. + user: + $ref: '#/components/schemas/UserlandUser' + description: >- + The user that belongs to the organization through this + membership. + required: + - object + - id + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + - role + - user + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + A pending organization membership cannot be reactivated. + The user needs to accept the invitation instead. + code: + type: string + description: The error code identifying the type of error. + example: cannot_reactivate_pending_organization_membership + const: cannot_reactivate_pending_organization_membership + required: + - message + - code + '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: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Role 'invalid_slug' is not a valid role. + code: + type: string + description: The error code identifying the type of error. + example: invalid_role + const: invalid_role + required: + - message + - code + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Multiple roles are not enabled for this environment. + code: + type: string + description: The error code identifying the type of error. + example: multiple_roles_not_enabled + const: multiple_roles_not_enabled + required: + - message + - code + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Sub-resource scoped roles are not allowed for this + operation. + code: + type: string + description: The error code identifying the type of error. + example: sub_resource_scoped_role_not_allowed + const: sub_resource_scoped_role_not_allowed + role_slug: + type: string + description: The slug of the role that is not allowed. + example: admin + required: + - message + - code + - role_slug + tags: + - user-management.organization-membership + x-mutually-exclusive-body-groups: &ref_9 + role: + optional: true + variants: + single: + - role_slug + multiple: + - role_slugs + /user_management/organization_memberships/{id}: + get: + operationId: UserlandUserOrganizationMembershipsController_get + summary: Get an organization membership + description: Get the details of an existing organization membership. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserOrganizationMembership' + '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 + tags: + - user-management.organization-membership + delete: + operationId: UserlandUserOrganizationMembershipsController_delete + summary: Delete an organization membership + description: >- + Permanently deletes an existing organization membership. It cannot be + undone. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + responses: + '200': + description: OK + '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 + tags: + - user-management.organization-membership + put: + operationId: UserlandUserOrganizationMembershipsController_update + summary: Update an organization membership + description: Update the details of an existing organization membership. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserlandUserOrganizationMembershipDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserOrganizationMembership' + '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: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Role 'invalid_slug' is not a valid role. + code: + type: string + description: The error code identifying the type of error. + example: invalid_role + const: invalid_role + required: + - message + - code + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: Multiple roles are not enabled for this environment. + code: + type: string + description: The error code identifying the type of error. + example: multiple_roles_not_enabled + const: multiple_roles_not_enabled + required: + - message + - code + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Sub-resource scoped roles are not allowed for this + operation. + code: + type: string + description: The error code identifying the type of error. + example: sub_resource_scoped_role_not_allowed + const: sub_resource_scoped_role_not_allowed + role_slug: + type: string + description: The slug of the role that is not allowed. + example: admin + required: + - message + - code + - role_slug + tags: + - user-management.organization-membership + x-mutually-exclusive-body-groups: &ref_10 + role: + optional: true + variants: + single: + - role_slug + multiple: + - role_slugs + /user_management/organization_memberships/{id}/deactivate: + put: + operationId: UserlandUserOrganizationMembershipsController_deactivate + summary: Deactivate an organization membership + description: >- + Deactivates an `active` organization membership. Emits an + [organization_membership.updated](/events/organization-membership) event + upon successful deactivation. + + + - Deactivating an `inactive` membership is a no-op and does not emit an + event. + + - Deactivating a `pending` membership returns an error. This membership + should be [deleted](/reference/authkit/organization-membership/delete) + instead. + + + See the [membership management + documentation](/authkit/users-organizations/organizations/membership-management) + for additional details. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of + `active`, `inactive`, or `pending`. + example: inactive + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a + directory sync connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the + linked [Directory + User](/reference/directory-sync/directory-user) or [SSO + Profile](/reference/sso/profile). Directory User + attributes take precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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' + role: + $ref: '#/components/schemas/SlimRole' + description: >- + The primary role assigned to the user within the + organization. + user: + $ref: '#/components/schemas/UserlandUser' + description: >- + The user that belongs to the organization through this + membership. + required: + - object + - id + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + - role + - user + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + A pending organization membership cannot be deactivated. + This membership should be deleted instead. + code: + type: string + description: The error code identifying the type of error. + example: cannot_deactivate_pending_organization_membership + const: cannot_deactivate_pending_organization_membership + required: + - message + - code + '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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.organization-membership + /user_management/organization_memberships/{id}/reactivate: + put: + operationId: UserlandUserOrganizationMembershipsController_reactivate + summary: Reactivate an organization membership + description: >- + Reactivates an `inactive` organization membership, retaining the + pre-existing role(s). Emits an + [organization_membership.updated](/events/organization-membership) event + upon successful reactivation. + + + - Reactivating an `active` membership is a no-op and does not emit an + event. + + - Reactivating a `pending` membership returns an error. The user needs + to [accept the invitation](/authkit/invitations) instead. + + + See the [membership management + documentation](/authkit/users-organizations/organizations/membership-management) + for additional details. + parameters: + - name: id + required: true + in: path + description: The unique ID of the organization membership. + schema: + example: om_01HXYZ123456789ABCDEFGHIJ + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserOrganizationMembership' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + A pending organization membership cannot be reactivated. + The user needs to accept the invitation instead. + code: + type: string + description: The error code identifying the type of error. + example: cannot_reactivate_pending_organization_membership + const: cannot_reactivate_pending_organization_membership + required: + - message + - code + '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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.organization-membership + /user_management/organization_memberships/{omId}/groups: + get: + operationId: OrganizationMembershipGroupsController_listGroups + summary: List groups + description: Get a list of groups that an organization membership belongs to. + parameters: + - name: omId + required: true + in: path + description: Unique identifier of the Organization Membership. + schema: + type: string + example: om_01HXYZ123456789ABCDEFGHIJ + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GroupList' + '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 + tags: + - user-management.organization-membership.groups + x-feature-flag: user-groups-enabled + /user_management/password_reset: + post: + operationId: UserlandUsersController_createPasswordResetToken + summary: Create a password reset token + description: Creates a one-time token that can be used to reset a user's password. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreatePasswordResetTokenDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordReset' + '403': + description: Forbidden + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_password_auth_disabled + const: email_password_auth_disabled + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_reset_not_allowed + const: password_reset_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - user-management.users + x-sends-email: true + /user_management/password_reset/confirm: + post: + operationId: UserlandUsersController_resetPassword + summary: Reset the password + description: >- + Sets a new password using the `token` query parameter from the link that + the user received. Successfully resetting the password will verify a + user's email, if it hasn't been verified yet. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreatePasswordResetDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ResetPasswordResponse' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_reset_error + const: password_reset_error + 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: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + '403': + description: Forbidden + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_password_auth_disabled + const: email_password_auth_disabled + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.users + /user_management/password_reset/{id}: + get: + operationId: UserlandUsersController_getPasswordReset + summary: Get a password reset token + description: >- + Get the details of an existing password reset token that can be used to + reset a user's password. + parameters: + - name: id + required: true + in: path + description: The ID of the password reset token. + schema: + type: string + example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/PasswordReset' + '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 + tags: + - user-management.users + /user_management/redirect_uris: + post: + operationId: RedirectUrisController_create + summary: Create a redirect URI + description: Creates a new redirect URI for an environment. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateRedirectUriDto' + responses: + '201': + description: Redirect URI created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/RedirectUri' + example: + object: redirect_uri + id: ruri_01EHZNVPK3SFK441A1RGBFSHRT + uri: https://example.com/callback + default: true + created_at: '2026-01-15T12:00:00.000Z' + updated_at: '2026-01-15T12:00:00.000Z' + '400': + description: Bad Request + 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 + example: + message: Bad Request + '401': + description: Unauthorized + 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 + example: + message: Unauthorized + '422': + description: Validation failed. + 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 + example: + message: Redirect URI 'https://example.com/callback' already exists. + tags: + - user-management.redirect-uris + /user_management/sessions/logout: + get: + operationId: UserlandSessionsController_logout + summary: Logout + security: [] + description: Logout a user from the current [session](/reference/authkit/session). + parameters: + - name: session_id + required: true + in: query + description: >- + The ID of the session to revoke. This can be extracted from the + `sid` claim of the access token. + schema: + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + type: string + - name: return_to + required: false + in: query + description: The URL to redirect the user to after session revocation. + schema: + example: https://example.com + type: string + responses: + '200': + headers: + location: + schema: + type: string + format: uri + description: OK + '302': + headers: + location: + schema: + type: string + format: uri + description: '' + '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 + tags: + - user-management.authentication + /user_management/sessions/revoke: + post: + operationId: UserlandSessionsController_revokeSession + summary: Revoke Session + description: Revoke a [user session](/reference/authkit/session). + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandRevokeSessionDto' + responses: + '200': + description: OK + '400': + description: Bad Request + 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 + tags: + - user-management.authentication + /user_management/users: + get: + operationId: UserlandUsersController_list + summary: List users + description: >- + Get a list of all of your existing users matching the criteria + specified. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - name: organization + required: false + in: query + deprecated: true + description: >- + Filter users by the organization they are a member of. Deprecated in + favor of `organization_id`. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: organization_id + required: false + in: query + description: Filter users by the organization they are a member of. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: email + required: false + in: query + description: Filter users by their email address. + schema: + example: user@example.com + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserList' + '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 + tags: + - user-management.users + post: + operationId: UserlandUsersController_create + summary: Create a user + description: Create a new user in the current environment. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserlandUserDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUser' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_strength_error + const: password_strength_error + 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: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: user_creation_error + const: user_creation_error + 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: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_password_hash + const: invalid_password_hash + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_provided + const: password_and_password_hash_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_type_provided + const: password_and_password_hash_type_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_metadata + const: invalid_metadata + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.users + x-mutually-exclusive-body-groups: &ref_11 + password: + optional: true + variants: + plaintext: + - password + hashed: + - password_hash + - password_hash_type + /user_management/users/external_id/{external_id}: + get: + operationId: UserlandUsersController_getByExternalId + summary: Get a user by external ID + description: >- + Get the details of an existing user by an [external + identifier](/authkit/metadata/external-identifiers). + parameters: + - name: external_id + required: true + in: path + description: The external ID of the user. + schema: + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUser' + '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 + tags: + - user-management.users + /user_management/users/{id}: + put: + operationId: UserlandUsersController_update + summary: Update a user + description: >- + Updates properties of a user. The omitted properties will be left + unchanged. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserlandUserDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUser' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_strength_error + const: password_strength_error + 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: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_password_hash + const: invalid_password_hash + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_provided + const: password_and_password_hash_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: password_and_password_hash_type_provided + const: password_and_password_hash_type_provided + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_already_verified + const: email_already_verified + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_metadata + const: invalid_metadata + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_id_already_used + const: external_id_already_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_not_allowed + const: email_change_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_not_available + const: email_not_available + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_email + const: invalid_email + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_locale + const: invalid_locale + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.users + x-mutually-exclusive-body-groups: &ref_14 + password: + optional: true + variants: + plaintext: + - password + hashed: + - password_hash + - password_hash_type + get: + operationId: UserlandUsersController_get + summary: Get a user + description: Get the details of an existing user. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUser' + '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 + tags: + - user-management.users + delete: + operationId: UserlandUsersController_delete + summary: Delete a user + description: >- + Permanently deletes a user in the current environment. It cannot be + undone. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + '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 + tags: + - user-management.users + /user_management/users/{id}/email_change/confirm: + post: + operationId: UserlandUsersController_confirmEmailChange + summary: Confirm email change + description: Confirms an email change using the one-time code received by the user. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ConfirmEmailChangeDto' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: Distinguishes the email change confirmation object. + const: email_change_confirmation + user: + type: object + properties: + object: + type: string + description: Distinguishes the user object. + const: user + id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + 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 + profile_picture_url: + type: + - string + - 'null' + description: A URL reference to an image representing the user. + example: https://workoscdn.com/images/v1/123abc + email: + type: string + description: The email address of the user. + example: new.email@example.com + email_verified: + type: boolean + description: Whether the user's email has been verified. + example: true + external_id: + type: + - string + - 'null' + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 + description: >- + Object containing metadata key/value pairs associated + with the user. + example: + timezone: America/New_York + propertyNames: + maxLength: 40 + maxProperties: 50 + last_sign_in_at: + format: date-time + type: + - string + - 'null' + description: The timestamp when the user last signed in. + example: '2025-06-25T19:07:33.155Z' + locale: + type: + - string + - 'null' + description: The user's preferred locale. + example: en-US + 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 + - first_name + - last_name + - profile_picture_url + - email + - email_verified + - external_id + - last_sign_in_at + - created_at + - updated_at + description: The user object. + required: + - object + - user + x-inline-with-overrides: true + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_code_expired + const: email_change_code_expired + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_code_incorrect + const: email_change_code_incorrect + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: no_pending_email_change + const: no_pending_email_change + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_code_previously_used + const: email_change_code_previously_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_not_available + const: email_not_available + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_not_allowed + const: email_change_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '422': + description: Unprocessable Entity + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_email + const: invalid_email + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_too_many_attempts + const: email_change_too_many_attempts + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - user-management.users + /user_management/users/{id}/email_change/send: + post: + operationId: UserlandUsersController_sendEmailChange + summary: Send email change code + description: >- + Sends an email that contains a one-time code used to change a user's + email address. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SendEmailChangeDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/EmailChange' + '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 + '409': + description: '' + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_not_needed + const: email_change_not_needed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_not_available + const: email_not_available + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_change_not_allowed + const: email_change_not_allowed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '422': + description: Unprocessable Entity + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_email + const: invalid_email + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - user-management.users + x-sends-email: true + /user_management/users/{id}/email_verification/confirm: + post: + operationId: UserlandUsersController_emailVerification + summary: Verify email + description: Verifies an email address using the one-time code received by the user. + parameters: + - name: id + required: true + in: path + description: The ID of the user. + schema: + type: string + example: user_01E4ZCR3C56J083X43JQXF3JK5 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyEmailAddressDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyEmailResponse' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_previously_verified + const: email_previously_verified + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_verification_code_previously_used + const: email_verification_code_previously_used + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_verification_code_expired + const: email_verification_code_expired + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_verification_code_incorrect + const: email_verification_code_incorrect + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.users + /user_management/users/{id}/email_verification/send: + post: + operationId: UserlandUsersController_sendVerificationEmail + summary: Send verification email + description: >- + Sends an email that contains a one-time code used to verify a user’s + email address. + parameters: + - name: id + required: true + in: path + description: The ID of the user. + schema: + type: string + example: user_01E4ZCR3C56J083X43JQXF3JK5 + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/SendVerificationEmailResponse' + '400': + description: Bad Request + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_already_verified + const: email_already_verified + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - 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 + '429': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: daily_quota_exceeded + const: daily_quota_exceeded + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - user-management.users + /user_management/users/{id}/identities: + get: + operationId: UserlandUserIdentitiesController_get + summary: Get user identities + description: >- + Get a list of identities associated with the user. A user can have + multiple associated identities after going through [identity + linking](/authkit/identity-linking). Currently only OAuth identities are + supported. More provider types may be added in the future. + parameters: + - name: id + required: true + in: path + description: The unique ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + type: object + properties: + idp_id: + type: string + description: >- + The unique ID of the user in the external identity + provider. + example: 4F42ABDE-1E44-4B66-824A-5F733C037A6D + type: + type: string + description: The type of the identity. + const: OAuth + provider: + type: string + enum: + - AppleOAuth + - BitbucketOAuth + - DiscordOAuth + - GithubOAuth + - GitLabOAuth + - GoogleOAuth + - IntuitOAuth + - LinkedInOAuth + - MicrosoftOAuth + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - XeroOAuth + description: The type of OAuth provider for the identity. + example: MicrosoftOAuth + required: + - idp_id + - type + - provider + '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 + tags: + - user-management.users + /user_management/users/{id}/sessions: + get: + operationId: UserlandUserSessionsController_list + summary: List sessions + description: Get a list of all active sessions for a specific user. + parameters: + - name: id + required: true + in: path + description: The ID 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. 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + allOf: + - type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + 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: session_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: session_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. + - type: object + properties: + data: + type: array + description: The list of records for the current page. + items: + type: object + properties: + object: + type: string + description: Distinguishes the session object. + const: session + id: + type: string + description: The unique ID of the session. + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + impersonator: + type: object + properties: + email: + type: string + description: >- + The email address of the WorkOS Dashboard + user who is impersonating the user. + example: admin@foocorp.com + reason: + type: + - string + - 'null' + description: >- + The justification the impersonator gave for + impersonating the user. + example: >- + Investigating an issue with the customer's + account. + required: + - email + - reason + description: >- + Information about the impersonator if this + session was created via impersonation. + ip_address: + type: + - string + - 'null' + description: >- + The IP address from which the session was + created. + example: 198.51.100.42 + organization_id: + type: string + description: >- + The ID of the organization this session is + associated with. + example: org_01H945H0YD4F97JN9MATX7BYAG + user_agent: + type: + - string + - 'null' + description: >- + The user agent string from the device that + created the session. + example: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 + user_id: + type: string + description: The ID of the user this session belongs to. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + auth_method: + type: string + enum: + - cross_app_auth + - external_auth + - impersonation + - magic_code + - migrated_session + - oauth + - passkey + - password + - sso + - unknown + description: >- + The authentication method used to create this + session. + example: sso + status: + type: string + enum: + - active + - expired + - revoked + description: The current status of the session. + example: active + expires_at: + format: date-time + type: string + description: The timestamp when the session expires. + example: '2026-01-15T12:00:00.000Z' + ended_at: + format: date-time + type: + - string + - 'null' + description: The timestamp when the session ended. + example: null + 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 + - ip_address + - user_agent + - user_id + - auth_method + - status + - expires_at + - ended_at + - created_at + - updated_at + '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: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + message: + type: string + description: A human-readable description of the error. + example: Validation failed. + required: + - code + - message + tags: + - user-management.users + /user_management/users/{userId}/api_keys: + get: + operationId: UserApiKeysController_list + summary: List API keys for a user + description: Get a list of API keys owned by a specific user. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + - 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 + tags: + - api_keys + x-feature-flag: user-api-keys + post: + operationId: UserApiKeysController_create + summary: Create an API key for a user + description: >- + Create a new API key owned by a user. The user must have an active + membership in the specified organization. + 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 + tags: + - api_keys + x-feature-flag: user-api-keys + /user_management/users/{userId}/feature-flags: + get: + operationId: UserlandUserFeatureFlagsController_list + summary: List enabled feature flags for a user + description: >- + Get a list of all enabled feature flags for the provided user. This + includes feature flags enabled specifically for the user as well as any + organizations that the user is a member of. + parameters: + - name: userId + required: true + in: path + description: The ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/FlagList' + '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 + tags: + - user-management.users.feature-flags + /user_management/users/{user_id}/authorized_applications: + get: + operationId: AuthorizedApplicationsController_list + summary: List authorized applications + description: Get a list of all Connect applications that the user has authorized. + parameters: + - name: user_id + required: true + in: path + description: The ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizedConnectApplicationList' + '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 + tags: + - user-management.users.authorized-applications + /user_management/users/{user_id}/authorized_applications/{application_id}: + delete: + operationId: AuthorizedApplicationsController_delete + summary: Delete an authorized application + description: Delete an existing Authorized Connect Application. + parameters: + - name: application_id + required: true + in: path + description: The ID or client ID of the application. + schema: + example: conn_app_01HXYZ123456789ABCDEFGHIJ + type: string + - name: user_id + required: true + in: path + description: The ID of the user. + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + 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 + tags: + - user-management.users.authorized-applications + /user_management/users/{user_id}/connected_accounts/{slug}: + get: + operationId: DataIntegrationsUserManagementController_getUserDataInstallation + summary: Get a connected account + description: >- + Retrieves a user's [connected + account](/reference/pipes/connected-account) for a specific provider. + parameters: + - name: user_id + required: true + in: path + description: A [User](/reference/authkit/user) identifier. + schema: + example: user_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: slug + required: true + in: path + description: >- + The slug identifier of the provider (e.g., `github`, `slack`, + `notion`). + schema: + example: github + type: string + - name: organization_id + required: false + in: query + description: >- + An [Organization](/reference/organization) identifier. Optional + parameter if the connection is scoped to an organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + responses: + '200': + description: The connected account was retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ConnectedAccount' + '401': + description: The request is missing a valid API key. + '404': + description: The user, organization, or connected account was 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 + tags: + - user-management.data-providers + delete: + operationId: DataIntegrationsUserManagementController_deleteUserDataInstallation + summary: Delete a connected account + description: >- + Disconnects WorkOS's account for the user, including removing any stored + access and refresh tokens. The user will need to reauthorize if they + want to reconnect. This does not revoke access on the provider side. + parameters: + - name: user_id + required: true + in: path + description: A [User](/reference/authkit/user) identifier. + schema: + example: user_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: slug + required: true + in: path + description: >- + The slug identifier of the provider (e.g., `github`, `slack`, + `notion`). + schema: + example: github + type: string + - name: organization_id + required: false + in: query + description: >- + An [Organization](/reference/organization) identifier. Optional + parameter if the connection is scoped to an organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + responses: + '204': + description: The connected account was deleted successfully. + '401': + description: The request is missing a valid API key. + '404': + description: The user, organization, or connected account was 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 + tags: + - user-management.data-providers + /user_management/users/{user_id}/data_providers: + get: + operationId: DataIntegrationsUserManagementController_getUserDataIntegrations + summary: List providers + description: >- + Retrieves a list of available providers and the user's connection status + for each. Returns all providers configured for your environment, along + with the user's [connected account](/reference/pipes/connected-account) + information where applicable. + parameters: + - name: user_id + required: true + in: path + description: >- + A [User](/reference/authkit/user) identifier to list providers and + connected accounts for. + schema: + example: user_01EHZNVPK3SFK441A1RGBFSHRT + type: string + - name: organization_id + required: false + in: query + description: >- + An [Organization](/reference/organization) identifier. Optional + parameter to filter connections for a specific organization. + schema: + example: org_01EHZNVPK3SFK441A1RGBFSHRT + type: string + responses: + '200': + description: The list of data providers was retrieved successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/DataIntegrationsListResponse' + '401': + description: The request is missing a valid API key. + '404': + description: The user or organization was 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 + tags: + - user-management.data-providers + /user_management/users/{userlandUserId}/auth_factors: + post: + operationId: UserlandUserAuthenticationFactorsController_create + summary: Enroll an authentication factor + description: >- + Enrolls a user in a new [authentication + factor](/reference/authkit/mfa/authentication-factor). + parameters: + - name: userlandUserId + required: true + in: path + description: The ID of the [user](/reference/authkit/user). + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EnrollUserlandUserAuthenticationFactorDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: >- + #/components/schemas/UserlandUserAuthenticationFactorEnrollResponse + '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 + tags: + - user-management.multi-factor-authentication + get: + operationId: UserlandUserAuthenticationFactorsController_list + summary: List authentication factors + description: >- + Lists the [authentication + factors](/reference/authkit/mfa/authentication-factor) for a user. + parameters: + - name: userlandUserId + required: true + in: path + description: The ID of the [user](/reference/authkit/user). + schema: + example: user_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserlandUserAuthenticationFactorList' + '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 + tags: + - user-management.multi-factor-authentication + /webhook_endpoints: + get: + operationId: WebhookEndpointsController_list + summary: List Webhook Endpoints + description: Get a list of all of your existing webhook endpoints. + 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: + default: desc + example: desc + enum: + - normal + - desc + - asc + type: string + responses: + '200': + description: List of webhook endpoints. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointList' + tags: + - webhooks + post: + operationId: WebhookEndpointsController_create + summary: Create a Webhook Endpoint + description: Create a new webhook endpoint to receive event notifications. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateWebhookEndpointDto' + responses: + '201': + description: Webhook endpoint created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointJson' + '409': + description: A Webhook Endpoint with the same endpoint URL already exists. + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: duplicate_endpoint + const: duplicate_endpoint + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '422': + description: Unprocessable Entity + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_url + const: invalid_url + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + 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: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + tags: + - webhooks + /webhook_endpoints/{id}: + patch: + operationId: WebhookEndpointsController_update + summary: Update a Webhook Endpoint + description: Update the properties of an existing webhook endpoint. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Webhook Endpoint. + schema: + type: string + example: we_0123456789 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateWebhookEndpointDto' + responses: + '200': + description: Webhook endpoint updated successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/WebhookEndpointJson' + '404': + description: Webhook endpoint not found. + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: entity_not_found + const: entity_not_found + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '409': + description: A Webhook Endpoint with the same endpoint URL already exists. + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: duplicate_endpoint + const: duplicate_endpoint + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '422': + description: Unprocessable Entity + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_url + const: invalid_url + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request_parameters + const: invalid_request_parameters + 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: unknown_event_type + message: + type: string + description: >- + A human-readable description of the validation + error. + example: Invalid enum value. + required: + - code + - message + description: The list of validation errors. + required: + - code + - message + - errors + tags: + - webhooks + delete: + operationId: WebhookEndpointsController_delete + summary: Delete a Webhook Endpoint + description: Delete an existing webhook endpoint. + parameters: + - name: id + required: true + in: path + description: Unique identifier of the Webhook Endpoint. + schema: + type: string + example: we_0123456789 + responses: + '204': + description: Webhook endpoint deleted successfully. + '404': + description: Webhook endpoint not found. + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: entity_not_found + const: entity_not_found + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + tags: + - webhooks + /widgets/token: + post: + operationId: WidgetsPublicController_issueWidgetSessionToken + summary: Generate a widget token + description: >- + Generate a widget token scoped to an organization and user with the + specified scopes. + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/WidgetSessionTokenDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/WidgetSessionTokenResponse' + '400': + description: Bad Request + content: + application/json: + schema: + oneOf: + - type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: >- + Organization not found: + 'org_01EHQMYV6MBK39QC5PZXHY59C3'. + required: + - message + - type: object + properties: + message: + type: array + items: + type: string + description: A list of validation error messages. + example: + - organization_id must be a string + error: + type: string + description: The error type. + example: Bad Request + required: + - message + - error + '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 + tags: + - widgets +info: + title: WorkOS + 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 +tags: + - name: admin-portal + description: Endpoints for the Admin Portal API. + - name: api_keys + description: Manage API keys for environments. + - name: application.client-secrets + description: Manage client secrets for Connect Applications. + - name: applications + description: Manage Connect Applications. + - name: audit-logs + description: Create and query audit log events. + - name: authorization + description: Authorization and access control. + - name: connections + description: Manage SSO connections. + - name: directories + description: Manage directories. + - name: directory-groups + description: Manage directory groups. + - name: directory-users + description: Manage directory users. + - name: events + description: Query events and event streams. + - name: feature-flags + description: Manage feature flags. + - name: feature-flags.targets + description: Manage feature flag targets. + - name: groups + description: Organize and manage user groups within organizations. + - name: multi-factor-auth + description: Multi-factor authentication factor management. + - name: multi-factor-auth.challenges + description: Multi-factor authentication challenge verification. + - name: organization-domains + description: Manage organization domains. + - name: organizations + description: Manage organizations. + - name: organizations.api_keys + description: Manage organization-scoped API keys. + - name: organizations.feature-flags + description: Manage organization-scoped feature flags. + - name: permissions + description: Manage permissions. + - name: pipes + description: Data integration endpoints. + - name: radar + description: Radar fraud detection. + - name: sso + description: Single Sign-On endpoints. + - name: user-management.authentication + description: User authentication endpoints. + - name: user-management.cors-origins + description: Manage CORS origins for user management. + - name: user-management.data-providers + description: Manage data providers. + - name: user-management.invitations + description: Manage user invitations. + - name: user-management.jwt-template + description: Manage JWT templates. + - name: user-management.magic-auth + description: Magic auth endpoints. + - name: user-management.multi-factor-authentication + description: Multi-factor authentication endpoints. + - name: user-management.organization-membership + description: Manage user organization memberships. + - name: user-management.organization-membership.groups + description: Manage groups for a user organization membership. + - name: user-management.redirect-uris + description: Manage redirect URIs. + - name: user-management.session-tokens + description: Session token verification keys. + - name: user-management.users + description: Manage users. + - name: user-management.users.authorized-applications + description: Manage authorized applications for users. + - name: user-management.users.feature-flags + description: Manage user-scoped feature flags. + - name: webhooks + description: Manage webhooks. + - name: widgets + description: Widget endpoints. + - name: workos-connect + description: >- + A unified interface that simplifies authentication and authorization + across customers, partners, and external SaaS tools. +servers: + - url: https://api.workos.com + description: Production + - url: https://api.workos-test.com + description: Staging +components: + 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. + schemas: + UserObject: + type: object + properties: + id: + type: string + description: >- + Your application's user identifier, which will be stored as an + [`external_id`](/authkit/metadata/external-identifiers). Used for + upserting and deduplication. + example: user_12345 + email: + type: string + description: The user's email address. + example: marcelina.davis@example.com + first_name: + type: string + description: The user's first name. + example: Marcelina + last_name: + type: string + description: The user's last name. + example: Davis + metadata: + type: object + description: A set of key-value pairs to attach to the user. + additionalProperties: + type: string + maxLength: 600 + maxProperties: 50 + example: + department: Engineering + role: Developer + propertyNames: + maxLength: 40 + required: + - id + - email + UserConsentOption: + type: object + properties: + claim: + type: string + description: The claim name for this consent option. + example: tos_accepted + type: + type: string + description: The type of consent option. + const: enum + label: + type: string + description: A human-readable label for this consent option. + example: Terms of Service + choices: + type: array + description: The available choices for this consent option. + items: + type: object + properties: + value: + type: string + description: The value of this choice. + example: accepted + label: + type: string + description: A human-readable label for this choice. + example: I accept the Terms of Service + example: + - value: accepted + label: I accept the Terms of Service + required: + - claim + - type + - label + - choices + UserManagementLoginRequest: + type: object + properties: + external_auth_id: + type: string + description: Identifier provided when AuthKit redirected to your login page. + example: ext_auth_01HXYZ123456789ABCDEFGHIJ + user: + description: The user to create or update in AuthKit. + $ref: '#/components/schemas/UserObject' + user_consent_options: + description: >- + Array of [User Consent + Options](/reference/workos-connect/standalone/user-consent-options) + to store with the session. + type: array + items: + $ref: '#/components/schemas/UserConsentOption' + required: + - external_auth_id + - user + ValidateApiKeyDto: + type: object + properties: + value: + type: string + description: The value for an API key. + example: sk_example_1234567890abcdef + required: + - value + RedirectUriDto: + type: object + properties: + uri: + type: string + description: The redirect URI. + example: https://example.com/callback + default: + type: + - boolean + - 'null' + description: Whether this is the default redirect URI. + example: true + required: + - uri + CreateOAuthApplicationDto: + type: object + properties: + name: + type: string + description: The name of the application. + example: My Application + application_type: + type: string + description: The type of application to create. + const: oauth + description: + type: + - string + - 'null' + description: A description for the application. + example: An application for managing user access + scopes: + description: The OAuth scopes granted to the application. + example: &ref_1 + - openid + - profile + - email + type: + - array + - 'null' + items: + type: string + redirect_uris: + description: Redirect URIs for the application. + example: + - uri: https://example.com/callback + default: true + type: + - array + - 'null' + items: + $ref: '#/components/schemas/RedirectUriDto' + uses_pkce: + type: + - boolean + - 'null' + description: Whether the application uses PKCE (Proof Key for Code Exchange). + example: true + is_first_party: + type: boolean + description: >- + Whether this is a first-party application. Third-party applications + require an organization_id. + example: true + organization_id: + type: + - string + - 'null' + description: >- + The organization ID this application belongs to. Required when + is_first_party is false. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - name + - application_type + - is_first_party + CreateM2MApplicationDto: + type: object + properties: + name: + type: string + description: The name of the application. + example: My Application + application_type: + type: string + description: The type of application to create. + const: m2m + description: + type: + - string + - 'null' + description: A description for the application. + example: An application for managing user access + scopes: + description: The OAuth scopes granted to the application. + example: *ref_1 + type: + - array + - 'null' + items: + type: string + organization_id: + type: string + description: The organization ID this application belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - name + - application_type + - organization_id + UpdateOAuthApplicationDto: + type: object + properties: + name: + type: string + description: The name of the application. + example: My Application + description: + type: + - string + - 'null' + description: A description for the application. + example: An application for managing user access + scopes: + description: The OAuth scopes granted to the application. + example: + - openid + - profile + - email + type: + - array + - 'null' + items: + type: string + redirect_uris: + description: Updated redirect URIs for the application. OAuth applications only. + example: + - uri: https://example.com/callback + default: true + type: + - array + - 'null' + items: + $ref: '#/components/schemas/RedirectUriDto' + CreateApplicationSecretDto: + type: object + properties: {} + AuditLogEventActorDto: + type: object + properties: + id: + type: string + description: Actor identifier. + example: user_TF4C5938 + type: + type: string + description: Actor type. + example: user + name: + type: string + description: Optional actor name. + example: Jon Smith + metadata: + type: object + description: Additional data associated with the event or entity. + example: + owner: user_01GBTCQ2 + maxProperties: 50 + additionalProperties: false + patternProperties: &ref_2 + ^[a-zA-Z0-9_-]{0,40}$: + anyOf: + - type: string + maxLength: 500 + - type: number + - type: boolean + required: + - id + - type + AuditLogEventTargetDto: + type: object + properties: + id: + type: string + description: Target identifier. + example: user_TF4C5938 + type: + type: string + description: Target type. + example: user + name: + type: string + description: Optional target name. + example: Jon Smith + metadata: + type: object + description: Additional data associated with the event or entity. + example: + owner: user_01GBTCQ2 + maxProperties: 50 + additionalProperties: false + patternProperties: *ref_2 + required: + - id + - type + AuditLogEventContextDto: + type: object + properties: + location: + type: string + description: IP Address or some other geolocation identifier. + example: 123.123.123.123 + user_agent: + type: string + description: User agent string. + example: Chrome/104.0.0.0 + required: + - location + AuditLogEventDto: + type: object + properties: + action: + type: string + description: Identifier of what happened. + example: user.signed_in + occurred_at: + type: string + description: ISO-8601 value of when the action occurred. + example: '2026-02-02T16:35:39.317Z' + format: date-time + actor: + description: The entity that performed the action. + $ref: '#/components/schemas/AuditLogEventActorDto' + targets: + description: The resources affected by the action. + type: array + items: + $ref: '#/components/schemas/AuditLogEventTargetDto' + context: + description: Additional context about where and how the action occurred. + $ref: '#/components/schemas/AuditLogEventContextDto' + metadata: + type: object + description: Additional data associated with the event or entity. + example: + owner: user_01GBTCQ2 + maxProperties: 50 + additionalProperties: false + patternProperties: *ref_2 + version: + type: integer + description: What schema version the event is associated with. + example: 1 + required: + - action + - occurred_at + - actor + - targets + - context + AuditLogEventIngestionDto: + type: object + properties: + organization_id: + type: string + description: The unique ID of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + event: + description: The audit log event to create. + $ref: '#/components/schemas/AuditLogEventDto' + required: + - organization_id + - event + AuditLogExportCreationDto: + type: object + properties: + organization_id: + type: string + description: The unique ID of the Organization. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + range_start: + type: string + description: ISO-8601 value for start of the export range. + example: '2022-07-02T18:09:06.996Z' + range_end: + type: string + description: ISO-8601 value for end of the export range. + example: '2022-09-02T18:09:06.996Z' + actions: + description: List of actions to filter against. + example: + - user.signed_in + type: array + items: + type: string + actors: + description: Deprecated. Use `actor_names` instead. + deprecated: true + example: + - Jon Smith + type: array + items: + type: string + actor_names: + description: List of actor names to filter against. + example: + - Jon Smith + type: array + items: + type: string + actor_ids: + description: List of actor IDs to filter against. + example: + - user_01GBZK5MP7TD1YCFQHFR22180V + type: array + items: + type: string + targets: + description: List of target types to filter against. + example: + - team + type: array + items: + type: string + required: + - organization_id + - range_start + - range_end + UpdateAuditLogsRetentionDto: + type: object + properties: + retention_period_in_days: + type: integer + description: >- + The number of days Audit Log events will be retained. Valid values + are `30` and `365`. + example: 30 + required: + - retention_period_in_days + AuditLogSchemaActorDto: + type: object + properties: + metadata: + type: object + description: JSON schema for actor metadata. + example: + type: object + properties: + role: + type: string + required: + - metadata + AuditLogSchemaTargetDto: + type: object + properties: + type: + type: string + description: The type of the target resource. + example: invoice + metadata: + type: object + description: Optional JSON schema for target metadata. + example: + type: object + properties: + cost: + type: number + required: + - type + AuditLogSchemaDto: + type: object + properties: + actor: + description: The metadata schema for the actor. + $ref: '#/components/schemas/AuditLogSchemaActorDto' + targets: + description: The list of targets for the schema. + type: array + items: + $ref: '#/components/schemas/AuditLogSchemaTargetDto' + metadata: + type: object + description: Optional JSON schema for event metadata. + example: + type: object + properties: + transactionId: + type: string + required: + - targets + ChallengeAuthenticationFactorDto: + type: object + properties: + sms_template: + type: string + description: >- + A custom template for the SMS message. Use the {{code}} placeholder + to include the verification code. + example: Your verification code is {{code}}. + CheckAuthorizationDto: + allOf: + - type: object + properties: + permission_slug: + type: string + description: The slug of the permission to check. + example: posts:create + required: + - permission_slug + - oneOf: + - type: object + properties: + resource_id: + type: string + description: >- + The ID of the resource. Mutually exclusive with + `resource_external_id` and `resource_type_slug`. + example: resource_01HXYZ123456789ABCDEFGHIJ + required: + - resource_id + not: + anyOf: + - properties: + resource_external_id: + x-exclude-from-lint: true + required: + - resource_external_id + - properties: + resource_type_slug: + x-exclude-from-lint: true + required: + - resource_type_slug + - type: object + properties: + resource_external_id: + type: string + description: >- + The external ID of the resource. Required with + `resource_type_slug`. Mutually exclusive with `resource_id`. + example: my-custom-id + resource_type_slug: + type: string + description: >- + The slug of the resource type. Required with + `resource_external_id`. Mutually exclusive with + `resource_id`. + example: document + required: + - resource_external_id + - resource_type_slug + not: + anyOf: + - properties: + resource_id: + x-exclude-from-lint: true + required: + - resource_id + x-mutually-exclusive-body-groups: *ref_3 + AssignRoleDto: + allOf: + - type: object + properties: + role_slug: + type: string + description: The slug of the role to assign. + example: editor + required: + - role_slug + - oneOf: + - type: object + properties: + resource_id: + type: string + description: >- + The ID of the resource. Mutually exclusive with + `resource_external_id` and `resource_type_slug`. + example: authz_resource_01HXYZ123456789ABCDEFGH + required: + - resource_id + not: + anyOf: + - properties: + resource_external_id: + x-exclude-from-lint: true + required: + - resource_external_id + - properties: + resource_type_slug: + x-exclude-from-lint: true + required: + - resource_type_slug + - type: object + properties: + resource_external_id: + type: string + description: >- + The external ID of the resource. Required with + `resource_type_slug`. Mutually exclusive with `resource_id`. + example: project-ext-456 + resource_type_slug: + type: string + description: >- + The resource type slug. Required with + `resource_external_id`. Mutually exclusive with + `resource_id`. + example: project + required: + - resource_external_id + - resource_type_slug + not: + anyOf: + - properties: + resource_id: + x-exclude-from-lint: true + required: + - resource_id + x-mutually-exclusive-body-groups: *ref_4 + RemoveRoleDto: + allOf: + - type: object + properties: + role_slug: + type: string + description: The slug of the role to remove. + example: editor + required: + - role_slug + - oneOf: + - type: object + properties: + resource_id: + type: string + description: >- + The ID of the resource. Mutually exclusive with + `resource_external_id` and `resource_type_slug`. + example: authz_resource_01HXYZ123456789ABCDEFGH + required: + - resource_id + not: + anyOf: + - properties: + resource_external_id: + x-exclude-from-lint: true + required: + - resource_external_id + - properties: + resource_type_slug: + x-exclude-from-lint: true + required: + - resource_type_slug + - type: object + properties: + resource_external_id: + type: string + description: >- + The external ID of the resource. Required with + `resource_type_slug`. Mutually exclusive with `resource_id`. + example: external_01HXYZ123456789ABCDEFGH + resource_type_slug: + type: string + description: >- + The resource type slug. Required with + `resource_external_id`. Mutually exclusive with + `resource_id`. + example: project + required: + - resource_external_id + - resource_type_slug + not: + anyOf: + - properties: + resource_id: + x-exclude-from-lint: true + required: + - resource_id + x-mutually-exclusive-body-groups: *ref_5 + SetRolePermissionsDto: + type: object + properties: + permissions: + description: The permission slugs to assign to the role. + example: + - billing:read + - billing:write + - invoices:manage + - reports:view + type: array + items: + type: string + required: + - permissions + AddRolePermissionDto: + type: object + properties: + slug: + type: string + description: The slug of the permission to add to the role. + example: reports:export + required: + - slug + CreateOrganizationRoleDto: + type: object + properties: + slug: + type: string + maxLength: 48 + description: >- + A unique identifier for the role within the organization. When + provided, must begin with 'org-' and contain only lowercase letters, + numbers, hyphens, and underscores. When omitted, a slug is + auto-generated from the role name and a random suffix. + example: org-billing-admin + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Billing Administrator + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role's purpose. + example: Can manage billing and invoices + resource_type_slug: + type: string + maxLength: 48 + description: The slug of the resource type the role is scoped to. + example: organization + required: + - name + UpdateOrganizationRoleDto: + type: object + properties: + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Finance Administrator + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role's purpose. + example: Can manage all financial operations + CreateAuthorizationPermissionDto: + type: object + properties: + slug: + type: string + maxLength: 48 + description: >- + A unique key to reference the permission. Must be lowercase and + contain only letters, numbers, hyphens, underscores, colons, + periods, and asterisks. + example: documents:read + name: + type: string + maxLength: 48 + description: A descriptive name for the Permission. + example: View Documents + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the Permission. + example: Allows viewing document contents + resource_type_slug: + type: string + maxLength: 48 + description: The slug of the resource type this permission is scoped to. + example: document + required: + - slug + - name + UpdateAuthorizationPermissionDto: + type: object + properties: + name: + type: string + maxLength: 48 + description: A descriptive name for the Permission. + example: View Documents + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the Permission. + example: Allows viewing document contents + CreateRoleDto: + type: object + properties: + slug: + type: string + maxLength: 48 + description: A unique slug for the role. + example: editor + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Editor + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role. + example: Can edit resources + resource_type_slug: + type: string + maxLength: 48 + description: The slug of the resource type the role is scoped to. + example: organization + required: + - slug + - name + UpdateRoleDto: + type: object + properties: + name: + type: string + maxLength: 48 + description: A descriptive name for the role. + example: Super Administrator + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the role. + example: Full administrative access to all resources + UpdateAuthorizationResourceDto: + allOf: + - type: object + properties: + name: + type: string + maxLength: 48 + description: A display name for the resource. + example: Updated Name + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the resource. + example: Updated description + - oneOf: + - type: object + not: + anyOf: + - properties: + parent_resource_id: + x-exclude-from-lint: true + required: + - parent_resource_id + - properties: + parent_resource_external_id: + x-exclude-from-lint: true + required: + - parent_resource_external_id + - properties: + parent_resource_type_slug: + x-exclude-from-lint: true + required: + - parent_resource_type_slug + - type: object + properties: + parent_resource_id: + type: string + description: >- + The ID of the parent resource. Mutually exclusive with + `parent_resource_external_id` and + `parent_resource_type_slug`. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + required: + - parent_resource_id + not: + anyOf: + - properties: + parent_resource_external_id: + x-exclude-from-lint: true + required: + - parent_resource_external_id + - properties: + parent_resource_type_slug: + x-exclude-from-lint: true + required: + - parent_resource_type_slug + - type: object + properties: + parent_resource_external_id: + type: string + description: >- + The external ID of the parent resource. Required with + `parent_resource_type_slug`. Mutually exclusive with + `parent_resource_id`. + example: parent-workspace-01 + parent_resource_type_slug: + type: string + description: >- + The resource type slug of the parent resource. Required with + `parent_resource_external_id`. Mutually exclusive with + `parent_resource_id`. + example: workspace + required: + - parent_resource_external_id + - parent_resource_type_slug + not: + anyOf: + - properties: + parent_resource_id: + x-exclude-from-lint: true + required: + - parent_resource_id + x-mutually-exclusive-body-groups: *ref_0 + CreateAuthorizationResourceDto: + allOf: + - type: object + properties: + external_id: + type: string + maxLength: 128 + description: An external identifier for the resource. + example: my-workspace-01 + name: + type: string + maxLength: 48 + description: A display name for the resource. + example: Acme Workspace + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the resource. + example: Primary workspace for the Acme team + resource_type_slug: + type: string + description: The slug of the resource type. + example: workspace + organization_id: + type: string + description: The ID of the organization this resource belongs to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + required: + - external_id + - name + - resource_type_slug + - organization_id + - oneOf: + - type: object + not: + anyOf: + - properties: + parent_resource_id: + x-exclude-from-lint: true + required: + - parent_resource_id + - properties: + parent_resource_external_id: + x-exclude-from-lint: true + required: + - parent_resource_external_id + - properties: + parent_resource_type_slug: + x-exclude-from-lint: true + required: + - parent_resource_type_slug + - type: object + properties: + parent_resource_id: + type: + - string + - 'null' + description: >- + The ID of the parent resource. Mutually exclusive with + `parent_resource_external_id` and + `parent_resource_type_slug`. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + required: + - parent_resource_id + not: + anyOf: + - properties: + parent_resource_external_id: + x-exclude-from-lint: true + required: + - parent_resource_external_id + - properties: + parent_resource_type_slug: + x-exclude-from-lint: true + required: + - parent_resource_type_slug + - type: object + properties: + parent_resource_external_id: + type: string + description: >- + The external ID of the parent resource. Required with + `parent_resource_type_slug`. Mutually exclusive with + `parent_resource_id`. + example: parent-workspace-01 + parent_resource_type_slug: + type: string + description: >- + The resource type slug of the parent resource. Required with + `parent_resource_external_id`. Mutually exclusive with + `parent_resource_id`. + example: workspace + required: + - parent_resource_external_id + - parent_resource_type_slug + not: + anyOf: + - properties: + parent_resource_id: + x-exclude-from-lint: true + required: + - parent_resource_id + x-mutually-exclusive-body-groups: *ref_6 + CreateCorsOriginDto: + type: object + properties: + origin: + type: string + description: The origin URL to allow for CORS requests. + example: https://example.com + required: + - origin + CreateGroupMembershipDto: + type: object + properties: + organization_membership_id: + type: string + description: The ID of the Organization Membership to add to the group. + example: om_01HXYZ123456789ABCDEFGHIJ + required: + - organization_membership_id + CreateGroupDto: + type: object + properties: + name: + type: string + maxLength: 256 + description: The name of the Group. + example: Engineering + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the Group. + example: The engineering team + required: + - name + UpdateGroupDto: + type: object + properties: + name: + type: string + maxLength: 256 + description: The name of the Group. + example: Engineering + description: + type: + - string + - 'null' + maxLength: 150 + description: An optional description of the Group. + example: The engineering team + UpdateJwtTemplateDto: + type: object + properties: + content: + type: string + description: The JWT template content as a Liquid template string. + example: >- + {"urn:myapp:full_name": "{{user.first_name}} {{user.last_name}}", + "urn:myapp:email": "{{user.email}}"} + required: + - content + CreateOrganizationDomainDto: + type: object + properties: + domain: + type: string + description: The domain to add to the organization. + example: foo-corp.com + organization_id: + type: string + description: The ID of the organization to add the domain to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + required: + - domain + - organization_id + CreateOrganizationApiKeyDto: + type: object + properties: + name: + type: string + description: The name for the API key. + example: Production API Key + permissions: + description: The permission slugs to assign to the API key. + example: + - posts:read + - posts:write + type: array + items: + type: string + required: + - name + OrganizationDomainDataDto: + type: object + properties: + domain: + type: string + description: The domain value. + example: foo-corp.com + state: + type: string + enum: + - pending + - verified + description: The verification state of the domain. + example: verified + required: + - domain + - state + OrganizationDto: + type: object + properties: + name: + type: string + description: The name of the organization. + example: Foo Corp + allow_profiles_outside_organization: + type: boolean + description: >- + Whether the organization allows profiles from outside the + organization to sign in. + example: false + domains: + description: >- + The domains associated with the organization. Deprecated in favor of + `domain_data`. + example: + - example.com + type: array + items: + type: string + domain_data: + description: >- + The domains associated with the organization, including verification + state. + type: array + items: + $ref: '#/components/schemas/OrganizationDomainDataDto' + metadata: + type: + - object + - 'null' + additionalProperties: &ref_7 + type: string + maxLength: 600 + maxProperties: 50 + example: &ref_8 + tier: diamond + description: >- + Object containing [metadata](/authkit/metadata) key/value pairs + associated with the Organization. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + example: ext_12345 + description: An external identifier for the Organization. + required: + - name + UpdateOrganizationDto: + type: object + properties: + name: + type: string + description: The name of the organization. + example: Foo Corp + allow_profiles_outside_organization: + type: boolean + description: >- + Whether the organization allows profiles from outside the + organization to sign in. + example: false + domains: + description: >- + The domains associated with the organization. Deprecated in favor of + `domain_data`. + example: + - foo-corp.com + deprecated: true + type: array + items: + type: string + domain_data: + description: >- + The domains associated with the organization, including verification + state. + type: array + items: + $ref: '#/components/schemas/OrganizationDomainDataDto' + stripe_customer_id: + type: string + description: The Stripe customer ID associated with the organization. + example: cus_R9qWAGMQ6nGE7V + metadata: + type: + - object + - 'null' + additionalProperties: *ref_7 + maxProperties: 50 + example: *ref_8 + description: >- + Object containing [metadata](/authkit/metadata) key/value pairs + associated with the Organization. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + description: An external identifier for the Organization. + SsoIntentOptions: + type: object + properties: + bookmark_slug: + type: string + description: The bookmark slug to use for SSO. + example: chatgpt + provider_type: + type: string + description: The SSO provider type to configure. + example: GoogleSAML + const: GoogleSAML + DomainVerificationIntentOptions: + type: object + properties: + domain_name: + type: string + description: >- + The domain name to verify. When provided, the domain verification + flow will skip the domain entry form and go directly to the + verification step. + example: example.com + IntentOptions: + type: object + properties: + sso: + description: SSO-specific options for the Admin Portal. + $ref: '#/components/schemas/SsoIntentOptions' + domain_verification: + description: Domain verification-specific options for the Admin Portal. + $ref: '#/components/schemas/DomainVerificationIntentOptions' + GenerateLinkDto: + type: object + properties: + return_url: + type: string + description: >- + The URL to go to when an admin clicks on your logo in the Admin + Portal. If not specified, the return URL configured on the + [Redirects](https://dashboard.workos.com/redirects) page will be + used. + example: https://example.com/admin-portal/return + success_url: + type: string + description: >- + The URL to redirect the admin to when they finish setup. If not + specified, the success URL configured on the + [Redirects](https://dashboard.workos.com/redirects) page will be + used. + example: https://example.com/admin-portal/success + organization: + type: string + description: An [Organization](/reference/organization) identifier. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + intent: + type: string + description: |2- + + The intent of the Admin Portal. + - `sso` - Launch Admin Portal for creating SSO connections + - `dsync` - Launch Admin Portal for creating Directory Sync connections + - `audit_logs` - Launch Admin Portal for viewing Audit Logs + - `log_streams` - Launch Admin Portal for creating Log Streams + - `domain_verification` - Launch Admin Portal for Domain Verification + - `certificate_renewal` - Launch Admin Portal for renewing SAML Certificates + - `bring_your_own_key` - Launch Admin Portal for configuring Bring Your Own Key + example: sso + enum: + - sso + - dsync + - audit_logs + - log_streams + - domain_verification + - certificate_renewal + - bring_your_own_key + intent_options: + description: Options to configure the Admin Portal based on the intent. + $ref: '#/components/schemas/IntentOptions' + it_contact_emails: + description: >- + The email addresses of the IT contacts to grant access to the Admin + Portal for the given organization. Accepts up to 20 emails. + example: + - it-contact@example.com + maxItems: 20 + items: + type: string + type: array + required: + - organization + CreateRedirectUriDto: + type: object + properties: + uri: + type: string + description: The redirect URI to create. + example: https://example.com/callback + required: + - uri + EnrollUserlandUserAuthenticationFactorDto: + type: object + properties: + type: + type: string + description: The type of the factor to enroll. + example: totp + const: totp + totp_issuer: + type: string + description: >- + Your application or company name displayed in the user's + authenticator app. + example: WorkOS + totp_user: + type: string + description: The user's account name displayed in their authenticator app. + example: user@example.com + totp_secret: + type: string + description: >- + The Base32-encoded shared secret for TOTP factors. This can be + provided when creating the auth factor, otherwise it will be + generated. The algorithm used to derive TOTP codes is SHA-1, the + code length is 6 digits, and the timestep is 30 seconds – the secret + must be compatible with these parameters. + example: JBSWY3DPEHPK3PXP + required: + - type + CreateUserlandMagicCodeAndReturnDto: + type: object + properties: + email: + type: string + description: The email address to send the magic code to. + example: marcelina.davis@example.com + invitation_token: + type: string + description: The invitation token to associate with this magic code. + example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 + required: + - email + CreateUserlandUserInviteOptionsDto: + type: object + properties: + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + organization_id: + type: string + description: >- + The ID of the [organization](/reference/organization) that the + recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + role_slug: + type: string + description: >- + The [role](/authkit/roles) that the recipient will receive when they + join the organization in the invitation. + example: admin + expires_in_days: + type: integer + description: >- + How many days the invitations will be valid for. Must be between 1 + and 30 days. Defaults to 7 days if not specified. + example: 7 + inviter_user_id: + type: string + description: >- + The ID of the [user](/reference/authkit/user) who invites the + recipient. The invitation email will mention the name of this user. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + locale: + type: string + enum: + - af + - am + - ar + - bg + - bn + - bs + - ca + - cs + - da + - de + - de-DE + - el + - en + - en-AU + - en-CA + - en-GB + - en-US + - es + - es-419 + - es-ES + - es-US + - et + - fa + - fi + - fil + - fr + - fr-BE + - fr-CA + - fr-FR + - fy + - gl + - gu + - ha + - he + - hi + - hr + - hu + - hy + - id + - is + - it + - it-IT + - ja + - jv + - ka + - kk + - km + - kn + - ko + - lt + - lv + - mk + - ml + - mn + - mr + - ms + - my + - nb + - ne + - nl + - nl-BE + - nl-NL + - nn + - 'no' + - pa + - pl + - pt + - pt-BR + - pt-PT + - ro + - ru + - sk + - sl + - sq + - sr + - sv + - sw + - ta + - te + - th + - tr + - uk + - ur + - uz + - vi + - zh + - zh-CN + - zh-HK + - zh-TW + - zu + description: >- + The locale to use when rendering the invitation email. See + [supported locales](/authkit/hosted-ui/localization). + example: en + required: + - email + ResendUserlandUserInviteOptionsDto: + type: object + properties: + locale: + type: string + enum: + - af + - am + - ar + - bg + - bn + - bs + - ca + - cs + - da + - de + - de-DE + - el + - en + - en-AU + - en-CA + - en-GB + - en-US + - es + - es-419 + - es-ES + - es-US + - et + - fa + - fi + - fil + - fr + - fr-BE + - fr-CA + - fr-FR + - fy + - gl + - gu + - ha + - he + - hi + - hr + - hu + - hy + - id + - is + - it + - it-IT + - ja + - jv + - ka + - kk + - km + - kn + - ko + - lt + - lv + - mk + - ml + - mn + - mr + - ms + - my + - nb + - ne + - nl + - nl-BE + - nl-NL + - nn + - 'no' + - pa + - pl + - pt + - pt-BR + - pt-PT + - ro + - ru + - sk + - sl + - sq + - sr + - sv + - sw + - ta + - te + - th + - tr + - uk + - ur + - uz + - vi + - zh + - zh-CN + - zh-HK + - zh-TW + - zu + description: >- + The locale to use when rendering the invitation email. See + [supported locales](/authkit/hosted-ui/localization). + example: en + CreateUserlandUserOrganizationMembershipDto: + allOf: + - type: object + properties: + user_id: + type: string + description: The ID of the [user](/reference/authkit/user). + example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E + organization_id: + type: string + description: >- + The ID of the [organization](/reference/organization) which the + user belongs to. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + required: + - user_id + - organization_id + - oneOf: + - type: object + not: + anyOf: + - properties: + role_slug: + x-exclude-from-lint: true + required: + - role_slug + - properties: + role_slugs: + x-exclude-from-lint: true + required: + - role_slugs + - type: object + properties: + role_slug: + type: string + description: >- + A single role identifier. Defaults to `member` or the + explicit default role. Mutually exclusive with `role_slugs`. + example: admin + required: + - role_slug + not: + anyOf: + - properties: + role_slugs: + x-exclude-from-lint: true + required: + - role_slugs + - type: object + properties: + role_slugs: + description: >- + An array of role identifiers. Limited to one role when + Multiple Roles is disabled. Mutually exclusive with + `role_slug`. + example: + - admin + type: array + items: + type: string + required: + - role_slugs + not: + anyOf: + - properties: + role_slug: + x-exclude-from-lint: true + required: + - role_slug + x-mutually-exclusive-body-groups: *ref_9 + UpdateUserlandUserOrganizationMembershipDto: + x-mutually-exclusive-body-groups: *ref_10 + oneOf: + - type: object + not: + anyOf: + - properties: + role_slug: + x-exclude-from-lint: true + required: + - role_slug + - properties: + role_slugs: + x-exclude-from-lint: true + required: + - role_slugs + - type: object + properties: + role_slug: + type: string + description: >- + A single role identifier. Defaults to `member` or the explicit + default role. Mutually exclusive with `role_slugs`. + example: admin + required: + - role_slug + not: + anyOf: + - properties: + role_slugs: + x-exclude-from-lint: true + required: + - role_slugs + - type: object + properties: + role_slugs: + description: >- + An array of role identifiers. Limited to one role when Multiple + Roles is disabled. Mutually exclusive with `role_slug`. + example: + - admin + type: array + items: + type: string + required: + - role_slugs + not: + anyOf: + - properties: + role_slug: + x-exclude-from-lint: true + required: + - role_slug + 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 + CreateUserlandUserDto: + allOf: + - type: object + properties: + email: + type: string + 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 + email_verified: + type: + - boolean + - 'null' + description: Whether the user's email has been verified. + example: true + metadata: + type: + - object + - 'null' + additionalProperties: *ref_7 + maxProperties: 50 + example: &ref_12 + timezone: America/New_York + description: >- + Object containing metadata key/value pairs associated with the + user. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + required: + - email + - oneOf: + - type: object + not: + anyOf: + - properties: + password: + x-exclude-from-lint: true + required: + - password + - properties: + password_hash: + x-exclude-from-lint: true + required: + - password_hash + - properties: + password_hash_type: + x-exclude-from-lint: true + required: + - password_hash_type + - type: object + properties: + password: + type: + - string + - 'null' + description: >- + The password to set for the user. Mutually exclusive with + `password_hash` and `password_hash_type`. + example: strong_password_123! + required: + - password + not: + anyOf: + - properties: + password_hash: + x-exclude-from-lint: true + required: + - password_hash + - properties: + password_hash_type: + x-exclude-from-lint: true + required: + - password_hash_type + - type: object + properties: + password_hash: + type: string + description: >- + The hashed password to set for the user. Required with + `password_hash_type`. Mutually exclusive with `password`. + example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy + password_hash_type: + type: string + enum: &ref_13 + - bcrypt + - firebase-scrypt + - ssha + - scrypt + - pbkdf2 + - argon2 + description: >- + The algorithm originally used to hash the password, used + when providing a `password_hash`. Required with + `password_hash`. Mutually exclusive with `password`. + example: bcrypt + required: + - password_hash + - password_hash_type + not: + anyOf: + - properties: + password: + x-exclude-from-lint: true + required: + - password + x-mutually-exclusive-body-groups: *ref_11 + UpdateUserlandUserDto: + allOf: + - type: object + properties: + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + first_name: + type: string + description: The first name of the user. + example: Marcelina + last_name: + type: string + description: The last name of the user. + example: Davis + email_verified: + type: boolean + description: Whether the user's email has been verified. + example: true + metadata: + type: + - object + - 'null' + additionalProperties: *ref_7 + maxProperties: 50 + example: *ref_12 + description: >- + Object containing metadata key/value pairs associated with the + user. + propertyNames: + maxLength: 40 + external_id: + type: + - string + - 'null' + maxLength: 128 + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + locale: + type: + - string + - 'null' + description: The user's preferred locale. + example: en-US + - oneOf: + - type: object + not: + anyOf: + - properties: + password: + x-exclude-from-lint: true + required: + - password + - properties: + password_hash: + x-exclude-from-lint: true + required: + - password_hash + - properties: + password_hash_type: + x-exclude-from-lint: true + required: + - password_hash_type + - type: object + properties: + password: + type: string + description: >- + The password to set for the user. Mutually exclusive with + `password_hash` and `password_hash_type`. + example: strong_password_123! + required: + - password + not: + anyOf: + - properties: + password_hash: + x-exclude-from-lint: true + required: + - password_hash + - properties: + password_hash_type: + x-exclude-from-lint: true + required: + - password_hash_type + - type: object + properties: + password_hash: + type: string + description: >- + The hashed password to set for the user. Required with + `password_hash_type`. Mutually exclusive with `password`. + example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy + password_hash_type: + type: string + enum: *ref_13 + description: >- + The algorithm originally used to hash the password, used + when providing a `password_hash`. Required with + `password_hash`. Mutually exclusive with `password`. + example: bcrypt + required: + - password_hash + - password_hash_type + not: + anyOf: + - properties: + password: + x-exclude-from-lint: true + required: + - password + x-mutually-exclusive-body-groups: *ref_14 + VerifyEmailAddressDto: + type: object + properties: + code: + type: string + description: The one-time email verification code. + example: '123456' + required: + - code + CreatePasswordResetTokenDto: + type: object + properties: + email: + type: string + description: The email address of the user requesting a password reset. + example: marcelina.davis@example.com + required: + - email + CreatePasswordResetDto: + type: object + properties: + token: + type: string + description: The password reset token. + example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 + new_password: + type: string + description: The new password to set for the user. + example: strong_password_123! + required: + - token + - new_password + SendEmailChangeDto: + type: object + properties: + new_email: + type: string + description: The new email address to change to. + example: new.email@example.com + required: + - new_email + ConfirmEmailChangeDto: + type: object + properties: + code: + type: string + description: The one-time code used to confirm the email change. + example: '123456' + required: + - code + UserlandRevokeSessionDto: + type: object + properties: + session_id: + type: string + description: >- + The ID of the session to revoke. This can be extracted from the + `sid` claim of the access token. + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + return_to: + type: string + description: The URL to redirect the user to after session revocation. + example: https://example.com + required: + - session_id + CreateWebhookEndpointDto: + type: object + properties: + endpoint_url: + type: string + description: The HTTPS URL where webhooks will be sent. + example: https://example.com/webhooks + events: + type: array + description: The events that the Webhook Endpoint is subscribed to. + items: + type: string + enum: &ref_15 + - authentication.email_verification_succeeded + - authentication.magic_auth_failed + - authentication.magic_auth_succeeded + - authentication.mfa_succeeded + - authentication.oauth_failed + - authentication.oauth_succeeded + - authentication.password_failed + - authentication.password_succeeded + - authentication.passkey_failed + - authentication.passkey_succeeded + - authentication.sso_failed + - authentication.sso_started + - authentication.sso_succeeded + - authentication.sso_timed_out + - authentication.radar_risk_detected + - api_key.created + - api_key.revoked + - connection.activated + - connection.deactivated + - connection.saml_certificate_renewal_required + - connection.saml_certificate_renewed + - connection.deleted + - dsync.activated + - dsync.deleted + - dsync.group.created + - dsync.group.deleted + - dsync.group.updated + - dsync.group.user_added + - dsync.group.user_removed + - dsync.user.created + - dsync.user.deleted + - dsync.user.updated + - email_verification.created + - group.created + - group.deleted + - group.member_added + - group.member_removed + - group.updated + - flag.created + - flag.deleted + - flag.updated + - flag.rule_updated + - invitation.accepted + - invitation.created + - invitation.resent + - invitation.revoked + - magic_auth.created + - organization.created + - organization.deleted + - organization.updated + - organization_domain.created + - organization_domain.deleted + - organization_domain.updated + - organization_domain.verified + - organization_domain.verification_failed + - password_reset.created + - password_reset.succeeded + - user.created + - user.updated + - user.deleted + - organization_membership.created + - organization_membership.deleted + - organization_membership.updated + - role.created + - role.deleted + - role.updated + - organization_role.created + - organization_role.deleted + - organization_role.updated + - permission.created + - permission.deleted + - permission.updated + - session.created + - session.revoked + - waitlist_user.approved + - waitlist_user.created + - waitlist_user.denied + example: + - user.created + - dsync.user.created + required: + - endpoint_url + - events + UpdateWebhookEndpointDto: + type: object + properties: + endpoint_url: + type: string + description: The HTTPS URL where webhooks will be sent. + example: https://example.com/webhooks + status: + type: string + enum: + - enabled + - disabled + description: Whether the Webhook Endpoint is enabled or disabled. + example: enabled + events: + type: array + description: The events that the Webhook Endpoint is subscribed to. + items: + type: string + enum: *ref_15 + example: + - user.created + - dsync.user.created + WidgetSessionTokenDto: + type: object + properties: + organization_id: + type: string + description: The ID of the organization to scope the widget session to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + user_id: + type: string + description: The ID of the user to issue the widget session token for. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + scopes: + type: array + description: The scopes to grant the widget session. + items: + type: string + enum: + - widgets:users-table:manage + - widgets:domain-verification:manage + - widgets:sso:manage + - widgets:api-keys:manage + - widgets:dsync:manage + - widgets:audit-log-streaming:manage + example: + - widgets:users-table:manage + required: + - organization_id + TokenQueryDto: + type: object + properties: + client_id: + type: string + description: The client ID of the WorkOS environment. + example: client_01HZBC6N1EB1ZY7KG32X + client_secret: + type: string + description: The client secret of the WorkOS environment. + example: sk_example_123456789 + code: + type: string + description: The authorization code received from the authorization callback. + example: authorization_code_value + grant_type: + type: string + description: The grant type for the token request. + example: authorization_code + const: authorization_code + required: + - client_id + - client_secret + - code + - grant_type + ExternalAuthCompleteResponse: + type: object + properties: + redirect_uri: + type: string + description: URI to redirect the user back to AuthKit to complete the OAuth flow. + example: >- + https://your-authkit-domain.workos.com/oauth/authorize/complete?state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdGF0ZSI6InJhbmRvbV9zdGF0ZV9zdHJpbmciLCJpYXQiOjE3NDI2MDQ4NTN9.abc123def456ghi789 + required: + - redirect_uri + 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 + ApiKeyValidationResponse: + type: object + properties: + api_key: + oneOf: + - $ref: '#/components/schemas/ApiKey' + - type: 'null' + required: + - api_key + ConnectApplication: + allOf: + - type: object + properties: + object: + type: string + description: Distinguishes the connect application object. + example: connect_application + const: connect_application + id: + type: string + description: The unique ID of the connect application. + example: conn_app_01HXYZ123456789ABCDEFGHIJ + client_id: + type: string + description: The client ID of the connect application. + example: client_01HXYZ123456789ABCDEFGHIJ + description: + type: + - string + - 'null' + description: A description of the connect application. + example: An application for managing user access + name: + type: string + description: The name of the connect application. + example: My Application + scopes: + type: array + items: + type: string + description: The scopes available for this application. + example: + - openid + - profile + - email + 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 + - client_id + - description + - name + - scopes + - created_at + - updated_at + - oneOf: + - allOf: + - type: object + properties: + application_type: + type: string + description: The type of the application. + const: oauth + redirect_uris: + type: array + items: + type: object + properties: + uri: + type: string + format: uri + description: The redirect URI for the application. + example: https://example.com/callback + default: + type: boolean + description: Whether this is the default redirect URI. + example: true + required: + - uri + - default + description: The redirect URIs configured for this application. + uses_pkce: + type: boolean + description: Whether the application uses PKCE for authorization. + example: true + required: + - application_type + - redirect_uris + - uses_pkce + - oneOf: + - type: object + properties: + is_first_party: + type: boolean + description: >- + Whether the application is a first-party + application. + example: true + const: true + required: + - is_first_party + - type: object + properties: + is_first_party: + type: boolean + description: >- + Whether the application is a first-party + application. + example: false + const: false + was_dynamically_registered: + type: boolean + description: Whether the application was dynamically registered. + example: false + const: false + organization_id: + type: string + description: >- + The ID of the organization the application belongs + to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - is_first_party + - was_dynamically_registered + - organization_id + - type: object + properties: + is_first_party: + type: boolean + description: >- + Whether the application is a first-party + application. + example: false + const: false + was_dynamically_registered: + type: boolean + description: Whether the application was dynamically registered. + example: true + const: true + required: + - is_first_party + - was_dynamically_registered + - type: object + properties: + application_type: + type: string + description: The type of the application. + example: m2m + const: m2m + organization_id: + type: string + description: The ID of the organization the application belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - application_type + - organization_id + ConnectApplicationList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/ConnectApplication' + 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: conn_app_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: conn_app_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + AuthorizedConnectApplicationList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the authorized connect application object. + const: authorized_connect_application + id: + type: string + description: The unique ID of the authorized connect application. + example: authorized_connect_app_01HXYZ123456789ABCDEFGHIJ + granted_scopes: + type: array + items: + type: string + description: The scopes granted by the user to the application. + example: + - openid + - profile + - email + oauth_resource: + type: string + description: >- + The OAuth resource associated with the authorized connect + application, if one was requested. + example: https://api.example.com/resource + application: + $ref: '#/components/schemas/ConnectApplication' + required: + - object + - id + - granted_scopes + - application + 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: authorized_connect_app_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: authorized_connect_app_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + NewConnectApplicationSecret: + type: object + properties: + object: + type: string + description: Distinguishes the connect application secret object. + const: connect_application_secret + id: + type: string + description: The unique ID of the client secret. + example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q + secret_hint: + type: string + description: A hint showing the last few characters of the secret value. + example: abc123 + last_used_at: + type: + - string + - 'null' + description: >- + The timestamp when the client secret was last used, or null if never + used. + example: null + 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' + secret: + type: string + description: >- + The plaintext secret value. Only returned at creation time and + cannot be retrieved later. + example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz + required: + - object + - id + - secret_hint + - last_used_at + - created_at + - updated_at + - secret + AuditLogEventCreateResponse: + type: object + properties: + success: + type: boolean + description: Whether the Audit Log event was created successfully. + example: true + required: + - success + AuditLogExportJson: + type: object + properties: + object: + type: string + description: Distinguishes the Audit Log Export object. + example: audit_log_export + const: audit_log_export + id: + type: string + description: The unique ID of the Audit Log Export. + example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V + state: + type: string + enum: + - pending + - ready + - error + description: 'The state of the export. Possible values: pending, ready, error.' + example: ready + url: + type: + - string + - 'null' + description: >- + A URL to the CSV file. Only defined when the Audit Log Export is + ready. + example: https://exports.audit-logs.com/audit-log-exports/export.csv + 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 + - state + - created_at + - updated_at + AuditLogsRetentionJson: + type: object + properties: + retention_period_in_days: + type: + - integer + - 'null' + description: >- + The number of days Audit Log events will be retained before being + permanently deleted. Valid values are 30 and 365. + example: 30 + required: + - retention_period_in_days + AuditLogSchemaJson: + type: object + properties: + object: + type: string + description: Distinguishes the Audit Log Schema object. + example: audit_log_schema + const: audit_log_schema + version: + type: integer + description: The version of the schema. + example: 1 + actor: + type: object + properties: + metadata: + type: object + additionalProperties: {} + description: The JSON Schema definition for actor metadata. + required: + - metadata + description: The metadata schema for the actor. + example: + metadata: + type: object + properties: + role: + type: string + targets: + type: array + items: + type: object + properties: + type: + type: string + description: The type of the target resource. + example: invoice + metadata: + type: object + additionalProperties: {} + description: Additional data associated with the event or entity. + example: + type: object + properties: + cost: + type: number + required: + - type + description: The list of targets for the schema. + example: + - type: invoice + metadata: + type: object + properties: + cost: + type: number + metadata: + type: object + additionalProperties: {} + description: Additional data associated with the event or entity. + example: + type: object + properties: + transactionId: + type: string + created_at: + format: date-time + type: string + description: The timestamp when the Audit Log Schema was created. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - version + - targets + - created_at + AuditLogActionJson: + type: object + properties: + object: + type: string + description: Distinguishes the Audit Log Action object. + example: audit_log_action + const: audit_log_action + name: + type: string + description: Identifier of what action was taken. + example: user.viewed_invoice + schema: + $ref: '#/components/schemas/AuditLogSchemaJson' + description: The schema associated with the action. + 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 + - name + - schema + - created_at + - updated_at + AuthenticationChallenge: + type: object + properties: + object: + type: string + description: Distinguishes the authentication challenge object. + const: authentication_challenge + id: + type: string + description: The unique ID of the authentication challenge. + example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ + expires_at: + format: date-time + type: string + description: >- + The timestamp when the challenge will expire. Does not apply to TOTP + factors. + example: '2026-01-15T12:00:00.000Z' + code: + type: string + description: The one-time code for the challenge. + example: '123456' + authentication_factor_id: + type: string + description: The unique ID of the authentication factor the challenge belongs to. + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + 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 + - authentication_factor_id + - created_at + - updated_at + AuthenticationChallengeVerifyResponse: + type: object + properties: + challenge: + $ref: '#/components/schemas/AuthenticationChallenge' + description: The authentication challenge object. + valid: + type: boolean + description: Whether the code was valid. + example: true + required: + - challenge + - valid + AuthenticationFactorEnrolled: + type: object + properties: + object: + type: string + description: Distinguishes the authentication factor object. + const: authentication_factor + id: + type: string + description: The unique ID of the factor. + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + type: + type: string + enum: + - generic_otp + - sms + - totp + - webauthn + description: The type of the factor to enroll. + example: totp + user_id: + type: string + description: The ID of the [user](/reference/authkit/user). + example: user_01E4ZCR3C56J083X43JQXF3JK5 + sms: + type: object + properties: + phone_number: + type: string + description: The user's phone number for SMS-based authentication. + example: '+15005550006' + required: + - phone_number + description: SMS-based authentication factor details. + totp: + type: object + properties: + issuer: + type: string + description: >- + Your application or company name displayed in the user's + authenticator app. Defaults to your WorkOS team name. + example: WorkOS + user: + type: string + description: >- + The user's account name displayed in their authenticator app. + Defaults to the user's email. + example: user@example.com + secret: + type: string + description: >- + TOTP secret that can be manually entered into some authenticator + apps in place of scanning a QR code. + example: JBSWY3DPEHPK3PXP + qr_code: + type: string + description: Base64 encoded image containing scannable QR code. + example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... + uri: + type: string + description: The `otpauth` URI that is encoded by the provided `qr_code`. + example: >- + otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS + required: + - issuer + - user + - secret + - qr_code + - uri + description: >- + TOTP-based authentication factor details. Includes enrollment + secrets only available at creation time. + 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 + - type + - created_at + - updated_at + AuthenticationFactor: + type: object + properties: + object: + type: string + description: Distinguishes the authentication factor object. + const: authentication_factor + id: + type: string + description: The unique ID of the factor. + example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + type: + type: string + enum: + - generic_otp + - sms + - totp + - webauthn + description: The type of the factor to enroll. + example: totp + user_id: + type: string + description: The ID of the [user](/reference/authkit/user). + example: user_01E4ZCR3C56J083X43JQXF3JK5 + sms: + type: object + properties: + phone_number: + type: string + description: The user's phone number for SMS-based authentication. + example: '+15005550006' + required: + - phone_number + description: SMS-based authentication factor details. + totp: + type: object + properties: + issuer: + type: string + description: >- + Your application or company name displayed in the user's + authenticator app. Defaults to your WorkOS team name. + example: WorkOS + user: + type: string + description: >- + The user's account name displayed in their authenticator app. + Defaults to the user's email. + example: user@example.com + required: + - issuer + - user + description: TOTP-based authentication factor details. + 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 + - type + - created_at + - updated_at + AuthorizationCheck: + type: object + properties: + authorized: + type: boolean + description: >- + Whether the organization membership has the specified permission on + the resource. + example: true + required: + - authorized + AuthorizationResource: + type: object + properties: + object: + type: string + description: Distinguishes the Resource object. + const: authorization_resource + name: + type: string + description: A human-readable name for the Resource. + example: Website Redesign + description: + type: + - string + - 'null' + description: An optional description of the Resource. + example: Company website redesign project + organization_id: + type: string + description: The ID of the organization that owns the resource. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + parent_resource_id: + type: + - string + - 'null' + description: The ID of the parent resource, if this resource is nested. + example: authz_resource_01HXYZ123456789ABCDEFGHIJ + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: An identifier you provide to reference the resource in your system. + example: proj-456 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: project + 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 + - name + - description + - organization_id + - parent_resource_id + - id + - external_id + - resource_type_slug + - created_at + - updated_at + AuthorizationResourceList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/AuthorizationResource' + 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: authz_resource_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: authz_resource_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + AuthorizationPermission: + type: object + properties: + object: + type: string + description: Distinguishes the Permission object. + const: permission + id: + type: string + description: Unique identifier of the Permission. + example: perm_01HXYZ123456789ABCDEFGHIJ + slug: + type: string + description: >- + A unique key to reference the permission. Must be lowercase and + contain only letters, numbers, hyphens, underscores, colons, + periods, and asterisks. + example: documents:read + name: + type: string + description: A descriptive name for the Permission. + example: View Documents + description: + type: + - string + - 'null' + description: An optional description of the Permission. + example: Allows viewing document contents + system: + type: boolean + description: >- + Whether the permission is a system permission. System permissions + are managed by WorkOS and cannot be deleted. + example: false + resource_type_slug: + type: string + description: The slug of the resource type associated with the permission. + example: workspace + 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 + - slug + - name + - description + - system + - resource_type_slug + - created_at + - updated_at + AuthorizationPermissionList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/AuthorizationPermission' + 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: perm_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: perm_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + 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. + RoleAssignment: + type: object + properties: + object: + type: string + description: Distinguishes the role assignment object. + const: role_assignment + id: + type: string + description: Unique identifier of the role assignment. + example: role_assignment_01HXYZ123456789ABCDEFGH + role: + $ref: '#/components/schemas/SlimRole' + description: The role included in the assignment. + resource: + type: object + properties: + id: + type: string + description: The unique ID of the Resource. + example: authz_resource_01HXYZ123456789ABCDEFGH + external_id: + type: string + description: >- + An identifier you provide to reference the resource in your + system. + example: proj-456 + resource_type_slug: + type: string + description: The slug of the resource type this resource belongs to. + example: project + required: + - id + - external_id + - resource_type_slug + description: The resource to which the role is assigned. + 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 + - role + - resource + - created_at + - updated_at + RoleAssignmentList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/RoleAssignment' + 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: role_assignment_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: role_assignment_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + Role: + type: object + properties: + slug: + type: string + description: A unique slug for the role. + example: admin + object: + type: string + description: Distinguishes the role object. + example: role + const: role + id: + type: string + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 + name: + type: string + description: A descriptive name for the role. + example: Admin + description: + type: + - string + - 'null' + description: An optional description of the role. + example: Can manage all resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole + description: >- + Whether the role is scoped to the environment or an organization + (custom role). + example: EnvironmentRole + resource_type_slug: + type: string + description: The slug of the resource type the role is scoped to. + example: organization + permissions: + type: array + items: + type: string + description: The permission slugs assigned to the role. + 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: + - slug + - object + - id + - name + - description + - type + - resource_type_slug + - permissions + - created_at + - updated_at + RoleList: + type: object + properties: + object: + type: string + example: list + const: list + data: + type: array + items: + $ref: '#/components/schemas/Role' + description: The list of records for the current page. + required: + - object + - data + UserlandUser: + type: object + properties: + object: + type: string + description: Distinguishes the user object. + const: user + id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + 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 + profile_picture_url: + type: + - string + - 'null' + description: A URL reference to an image representing the user. + example: https://workoscdn.com/images/v1/123abc + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + email_verified: + type: boolean + description: Whether the user's email has been verified. + example: true + external_id: + type: + - string + - 'null' + description: The external ID of the user. + example: f1ffa2b2-c20b-4d39-be5c-212726e11222 + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 + description: Object containing metadata key/value pairs associated with the user. + example: + timezone: America/New_York + propertyNames: + maxLength: 40 + maxProperties: 50 + last_sign_in_at: + format: date-time + type: + - string + - 'null' + description: The timestamp when the user last signed in. + example: '2025-06-25T19:07:33.155Z' + locale: + type: + - string + - 'null' + description: The user's preferred locale. + example: en-US + 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 + - first_name + - last_name + - profile_picture_url + - email + - email_verified + - external_id + - last_sign_in_at + - created_at + - updated_at + description: The user object. + UserlandUserOrganizationMembershipBaseWithUser: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of `active`, + `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a directory sync + connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the linked + [Directory User](/reference/directory-sync/directory-user) or [SSO + Profile](/reference/sso/profile). Directory User attributes take + precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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' + user: + $ref: '#/components/schemas/UserlandUser' + description: The user that belongs to the organization through this membership. + required: + - object + - id + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + - user + UserlandUserOrganizationMembershipBaseWithUserList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseWithUser + 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: om_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: om_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + Connection: + type: object + properties: + object: + type: string + description: Distinguishes the Connection object. + const: connection + id: + type: string + description: Unique identifier for the Connection. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + organization_id: + type: string + description: >- + Unique identifier for the Organization in which the Connection + resides. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + connection_type: + type: string + enum: + - Pending + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: >- + The type of the SSO Connection used to authenticate the user. The + Connection type may be used to dynamically generate authorization + URLs. + example: OktaSAML + name: + type: string + description: >- + A human-readable name for the Connection. This will most commonly be + the organization's name. + example: Foo Corp + state: + type: string + enum: + - requires_type + - draft + - active + - validating + - inactive + - deleting + description: Indicates whether a Connection is able to authenticate users. + example: active + status: + type: string + enum: + - linked + - unlinked + description: Deprecated. Use `state` instead. + deprecated: true + example: linked + domains: + type: array + items: + type: object + properties: + id: + type: string + description: Unique identifier for the Connection Domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + object: + type: string + description: Distinguishes the Connection Domain object. + const: connection_domain + domain: + type: string + description: The domain value. + example: foo-corp.com + required: + - id + - object + - domain + description: List of Organization Domains. + options: + type: object + properties: + signing_cert: + type: + - string + - 'null' + description: The signing certificate of the SAML connection. + example: null + required: + - signing_cert + description: >- + Configuration options for SAML connections. Only present for SAML + connection types. + 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 + - connection_type + - name + - state + - status + - domains + - created_at + - updated_at + ConnectionList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Connection' + 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: conn_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: conn_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + - list_metadata + CorsOriginResponse: + type: object + properties: + object: + type: string + description: Distinguishes the CORS origin object. + const: cors_origin + id: + type: string + description: Unique identifier of the CORS origin. + example: cors_origin_01HXYZ123456789ABCDEFGHIJ + origin: + type: string + description: The origin URL. + example: https://example.com + created_at: + type: string + format: date-time + description: Timestamp when the CORS origin was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + format: date-time + description: Timestamp when the CORS origin was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - origin + - created_at + - updated_at + Directory: + type: object + properties: + object: + type: string + description: Distinguishes the Directory object. + const: directory + id: + type: string + description: Unique identifier for the Directory. + example: directory_01ECAZ4NV9QMV47GW873HDCX74 + organization_id: + type: string + description: >- + The unique identifier for the Organization in which the directory + resides. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + external_key: + type: string + description: External Key for the Directory. + example: sPa12dwRQ + type: + description: The type of external Directory Provider integrated with. + example: gsuite directory + type: string + enum: + - azure scim v2.0 + - bamboohr + - breathe hr + - cezanne hr + - cyberark scim v2.0 + - fourth hr + - generic scim v2.0 + - gsuite directory + - hibob + - sailpoint scim v2.0 + - jump cloud scim v2.0 + - okta scim v2.0 + - onelogin scim v2.0 + - people hr + - personio + - pingfederate scim v2.0 + - rippling scim v2.0 + - s3 + - sftp + - sftp workday + - workday + state: + description: >- + Describes whether the Directory has been successfully connected to + an external provider. + example: linked + type: string + enum: + - linked + - validating + - invalid_credentials + - unlinked + - deleting + name: + type: string + description: The name of the directory. + example: Foo Corp + domain: + type: string + description: The URL associated with an Enterprise Client. + example: foo-corp.com + metadata: + type: object + properties: + users: + type: object + properties: + active: + type: integer + description: Count of active directory users. + example: 42 + inactive: + type: integer + description: Count of inactive directory users. + example: 3 + required: + - active + - inactive + description: Counts of active and inactive directory users. + groups: + type: integer + description: Count of directory groups. + example: 5 + required: + - users + - groups + description: >- + Aggregate counts of directory users and groups synced from the + 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 + - organization_id + - external_key + - type + - state + - name + - created_at + - updated_at + DirectoryList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Directory' + 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_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_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 + DirectoryGroupList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/DirectoryGroup' + 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_group_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_group_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + - list_metadata + 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 + 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 + UserlandUserOrganizationMembershipBaseList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of `active`, + `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a directory + sync connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the linked + [Directory User](/reference/directory-sync/directory-user) or + [SSO Profile](/reference/sso/profile). Directory User + attributes take precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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 + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + 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: om_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: om_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + Group: + type: object + properties: + object: + type: string + description: The Group object. + example: group + const: group + id: + type: string + description: The unique ID of the Group. + example: group_01HXYZ123456789ABCDEFGHIJ + organization_id: + type: string + description: The ID of the Organization the Group belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: The name of the Group. + example: Engineering + description: + type: + - string + - 'null' + description: An optional description of the Group. + example: The engineering team + 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 + - organization_id + - name + - description + - created_at + - updated_at + GroupList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Group' + 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: group_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: group_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + EventContextActorDto: + type: object + properties: + id: + type: string + description: Unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + source: + type: string + enum: + - api + - dashboard + - admin_portal + - system + description: The source of the actor that performed the action. + name: + type: + - string + - 'null' + description: The name of the actor. + example: Jane Doe + required: + - id + - source + - name + description: The actor who performed the action. + EventContextDto: + type: object + properties: + google_analytics_client_id: + type: string + description: The Google Analytics client ID. + example: GA1.2.1234567890.1234567890 + google_analytics_sessions: + type: array + items: + type: object + properties: + containerId: + type: string + description: The Google Analytics container ID. + example: GTM-ABCDEF + sessionId: + type: string + description: The Google Analytics session ID. + example: '1234567890' + sessionNumber: + type: string + description: The Google Analytics session number. + example: '1' + required: + - containerId + description: The Google Analytics sessions associated with the event. + ajs_anonymous_id: + type: string + description: The anonymous ID from analytics. + example: ajs_anon_01EHWNCE74X7JSDV0X3SZ3KJNY + client_id: + type: string + description: The client ID associated with the event. + example: client_01EHWNCE74X7JSDV0X3SZ3KJNY + actor: + $ref: '#/components/schemas/EventContextActorDto' + previous_attributes: + type: object + additionalProperties: {} + description: Attributes that changed from their previous values. + description: Additional context about the event. + DirectoryUser: + 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: &ref_18 + 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' + required: + - object + - id + - directory_id + - organization_id + - idp_id + - email + - state + - raw_attributes + - custom_attributes + - created_at + - updated_at + WaitlistUser: + type: object + properties: + object: + type: string + description: Distinguishes the Waitlist User object. + const: waitlist_user + id: + type: string + description: The unique ID of the Waitlist User. + example: wl_user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the Waitlist User. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - approved + - denied + description: The state of the Waitlist User. + example: pending + approved_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the Waitlist User was approved, or null if not + yet approved. + example: null + 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 + - email + - state + - approved_at + - created_at + - updated_at + EventSchema: + allOf: + - type: object + properties: + object: + type: string + description: Distinguishes the Event object. + const: event + id: + type: string + description: Unique identifier for the Event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + description: The type of event that occurred. + example: dsync.user.created + data: + type: object + additionalProperties: {} + description: The event payload. + example: &ref_16 + id: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ + directory_id: directory_01ECAZ4NV9QMV47GW873HDCX74 + organization_id: org_01EZTR6WYX1A0DSE2CYMGXQ24Y + state: active + email: veda@foo-corp.com + emails: + - primary: true + type: work + value: veda@foo-corp.com + idp_id: '2836' + object: directory_user + username: veda@foo-corp.com + last_name: Torp + first_name: Veda + raw_attributes: {} + custom_attributes: {} + created_at: '2021-06-25T19:07:33.155Z' + updated_at: '2021-06-25T19:07:33.155Z' + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + type: object + additionalProperties: {} + description: Additional context about the event. + required: + - object + - id + - event + - data + - created_at + description: An event emitted by WorkOS. + example: &ref_23 + object: event + id: event_01EHZNVPK3SFK441A1RGBFSHRT + event: dsync.user.created + data: *ref_16 + created_at: '2021-06-25T19:07:33.155Z' + context: {} + - oneOf: + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: action.authentication.denied + data: + type: object + properties: + action_endpoint_id: + type: string + description: The ID of the action endpoint. + example: action_endpoint_01EHWNCE74X7JSDV0X3SZ3KJNY + action_execution_id: + type: string + description: The ID of the action execution. + example: action_execution_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + description: The type of action that was denied. + const: authentication + verdict: + type: string + description: The verdict of the action. + const: Deny + user_id: + type: string + description: The ID of the user. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: + - string + - 'null' + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + email: + type: string + description: The email address of the user. + example: user@example.com + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.1 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + required: + - action_endpoint_id + - action_execution_id + - type + - verdict + - user_id + - organization_id + - email + - ip_address + - user_agent + description: The event payload. + context: + $ref: '#/components/schemas/EventContextDto' + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: action.user_registration.denied + data: + type: object + properties: + action_endpoint_id: + type: string + description: The ID of the action endpoint. + example: action_endpoint_01EHWNCE74X7JSDV0X3SZ3KJNY + action_execution_id: + type: string + description: The ID of the action execution. + example: action_execution_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + description: The type of action that was denied. + const: user_registration + verdict: + type: string + description: The verdict of the action. + const: Deny + organization_id: + type: + - string + - 'null' + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + email: + type: string + description: The email address of the user. + example: user@example.com + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.1 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + required: + - action_endpoint_id + - action_execution_id + - type + - verdict + - organization_id + - email + - ip_address + - user_agent + description: The event payload. + context: + $ref: '#/components/schemas/EventContextDto' + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: api_key.created + data: + 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_01EHWNCE74X7JSDV0X3SZ3KJNY + owner: + oneOf: + - type: object + properties: + type: + type: string + description: The type of the API key owner. + const: organization + id: + type: string + description: The unique identifier of the API key owner. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - type + - id + - type: object + properties: + type: + type: string + description: The type of the API key owner. + const: user + id: + type: string + description: >- + The unique identifier of the user who owns the + API key. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: >- + The unique identifier of the organization the + API key belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - type + - id + - organization_id + description: The owner of the API key. + name: + type: string + description: The name of the API key. + example: My API Key + obfuscated_value: + type: string + description: The obfuscated value of the API key. + example: sk_test_...1234 + last_used_at: + type: + - string + - 'null' + description: The timestamp when the API key was last used. + example: '2026-01-15T12:00:00.000Z' + permissions: + type: array + items: + type: string + description: The permissions granted to the API key. + example: &ref_17 + - users:read + - users:write + created_at: + type: string + description: The timestamp when the API key was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the API key was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - owner + - name + - obfuscated_value + - last_used_at + - permissions + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: api_key.revoked + data: + 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_01EHWNCE74X7JSDV0X3SZ3KJNY + owner: + oneOf: + - type: object + properties: + type: + type: string + description: The type of the API key owner. + const: organization + id: + type: string + description: The unique identifier of the API key owner. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - type + - id + - type: object + properties: + type: + type: string + description: The type of the API key owner. + const: user + id: + type: string + description: >- + The unique identifier of the user who owns the + API key. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: >- + The unique identifier of the organization the + API key belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - type + - id + - organization_id + description: The owner of the API key. + name: + type: string + description: The name of the API key. + example: My API Key + obfuscated_value: + type: string + description: The obfuscated value of the API key. + example: sk_test_...1234 + last_used_at: + type: + - string + - 'null' + description: The timestamp when the API key was last used. + example: '2026-01-15T12:00:00.000Z' + permissions: + type: array + items: + type: string + description: The permissions granted to the API key. + example: *ref_17 + created_at: + type: string + description: The timestamp when the API key was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the API key was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - owner + - name + - obfuscated_value + - last_used_at + - permissions + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.email_verification_failed + data: + type: object + properties: + type: + type: string + const: email_verification + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.email_verification_succeeded + data: + type: object + properties: + type: + type: string + const: email_verification + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.magic_auth_failed + data: + type: object + properties: + type: + type: string + const: magic_auth + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.magic_auth_succeeded + data: + type: object + properties: + type: + type: string + const: magic_auth + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.mfa_failed + data: + type: object + properties: + type: + type: string + const: mfa + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.mfa_succeeded + data: + type: object + properties: + type: + type: string + const: mfa + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.oauth_failed + data: + type: object + properties: + type: + type: string + const: oauth + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.oauth_succeeded + data: + type: object + properties: + type: + type: string + const: oauth + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.passkey_failed + data: + type: object + properties: + type: + type: string + const: passkey + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.passkey_succeeded + data: + type: object + properties: + type: + type: string + const: passkey + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.password_failed + data: + type: object + properties: + type: + type: string + const: password + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.password_succeeded + data: + type: object + properties: + type: + type: string + const: password + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.radar_risk_detected + data: + type: object + properties: + auth_method: + type: string + description: The authentication method used. + example: password + action: + type: string + enum: + - signup + - login + control: + type: + - string + - 'null' + description: The control action taken for the detected risk. + example: block + blocklist_type: + type: + - string + - 'null' + description: The type of blocklist that triggered the risk detection. + example: ip + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + required: + - auth_method + - action + - control + - blocklist_type + - ip_address + - user_agent + - user_id + - email + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.sso_failed + data: + type: object + properties: + type: + type: string + const: sso + status: + type: string + const: failed + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + sso: + type: object + properties: + organization_id: + type: + - string + - 'null' + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + connection_id: + type: + - string + - 'null' + description: The ID of the SSO connection. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + session_id: + type: + - string + - 'null' + description: The ID of the SSO session. + example: sess_01E4ZCR3C56J083X43JQXF3JK5 + required: + - organization_id + - connection_id + - session_id + description: SSO connection details. + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - sso + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.sso_started + data: + type: object + properties: + type: + type: string + const: sso + status: + type: string + const: started + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + sso: + type: object + properties: + organization_id: + type: + - string + - 'null' + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + connection_id: + type: + - string + - 'null' + description: The ID of the SSO connection. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + session_id: + type: + - string + - 'null' + description: The ID of the SSO session. + example: sess_01E4ZCR3C56J083X43JQXF3JK5 + required: + - organization_id + - connection_id + - session_id + description: SSO connection details. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - sso + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.sso_succeeded + data: + type: object + properties: + type: + type: string + const: sso + status: + type: string + const: succeeded + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: user@example.com + sso: + type: object + properties: + organization_id: + type: + - string + - 'null' + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + connection_id: + type: + - string + - 'null' + description: The ID of the SSO connection. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + session_id: + type: + - string + - 'null' + description: The ID of the SSO session. + example: sess_01E4ZCR3C56J083X43JQXF3JK5 + required: + - organization_id + - connection_id + - session_id + description: SSO connection details. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - sso + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: authentication.sso_timed_out + data: + type: object + properties: + type: + type: string + const: sso + status: + type: string + const: timed_out + ip_address: + type: + - string + - 'null' + description: The IP address of the request. + example: 203.0.113.42 + user_agent: + type: + - string + - 'null' + description: The user agent of the request. + example: Mozilla/5.0 + user_id: + type: + - string + - 'null' + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: + - string + - 'null' + description: The email address of the user. + example: user@example.com + sso: + type: object + properties: + organization_id: + type: + - string + - 'null' + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + connection_id: + type: + - string + - 'null' + description: The ID of the SSO connection. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + session_id: + type: + - string + - 'null' + description: The ID of the SSO session. + example: sess_01E4ZCR3C56J083X43JQXF3JK5 + required: + - organization_id + - connection_id + - session_id + description: SSO connection details. + error: + type: object + properties: + code: + type: string + description: The error code. + example: mfa_challenge_failed + message: + type: string + description: A human-readable error message. + example: The MFA challenge has failed. + required: + - code + - message + description: Details about the authentication error. + required: + - type + - status + - ip_address + - user_agent + - user_id + - email + - sso + - error + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: connection.activated + data: + type: object + properties: + object: + type: string + description: Distinguishes the connection object. + const: connection + id: + type: string + description: Unique identifier of the connection. + example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY + state: + type: string + enum: + - draft + - active + - validating + - inactive + - deleting + description: The current state of the connection. + example: active + name: + type: string + description: The name of the connection. + example: Acme SSO + connection_type: + type: string + enum: + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: The type of the connection. + example: OktaSAML + organization_id: + type: string + description: The ID of the organization the connection belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + 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' + external_key: + type: string + description: The external key of the connection. + example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY + status: + type: string + enum: + - linked + - unlinked + description: Deprecated. Use state instead. + example: linked + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the connection domain object. + const: connection_domain + id: + type: string + description: Unique identifier of the connection domain. + example: conn_domain_01EHWNCE74X7JSDV0X3SZ3KJNY + domain: + type: string + description: The domain value. + example: acme.com + required: + - object + - id + - domain + description: The domains associated with the connection. + required: + - object + - id + - state + - name + - connection_type + - created_at + - updated_at + - external_key + - status + - domains + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: connection.deactivated + data: + type: object + properties: + object: + type: string + description: Distinguishes the connection object. + const: connection + id: + type: string + description: Unique identifier of the connection. + example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY + state: + type: string + enum: + - draft + - active + - validating + - inactive + - deleting + description: The current state of the connection. + example: active + name: + type: string + description: The name of the connection. + example: Acme SSO + connection_type: + type: string + enum: + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: The type of the connection. + example: OktaSAML + organization_id: + type: string + description: The ID of the organization the connection belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + 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' + external_key: + type: string + description: The external key of the connection. + example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY + status: + type: string + enum: + - linked + - unlinked + description: Deprecated. Use state instead. + example: linked + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the connection domain object. + const: connection_domain + id: + type: string + description: Unique identifier of the connection domain. + example: conn_domain_01EHWNCE74X7JSDV0X3SZ3KJNY + domain: + type: string + description: The domain value. + example: acme.com + required: + - object + - id + - domain + description: The domains associated with the connection. + required: + - object + - id + - state + - name + - connection_type + - created_at + - updated_at + - external_key + - status + - domains + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: connection.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the connection object. + const: connection + id: + type: string + description: Unique identifier of the connection. + example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY + state: + type: string + enum: + - draft + - active + - validating + - inactive + - deleting + description: The current state of the connection. + example: active + name: + type: string + description: The name of the connection. + example: Acme SSO + connection_type: + type: string + enum: + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: The type of the connection. + example: OktaSAML + organization_id: + type: string + description: The ID of the organization the connection belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + 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 + - state + - name + - connection_type + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: connection.saml_certificate_renewal_required + data: + type: object + properties: + connection: + type: object + properties: + id: + type: string + description: Unique identifier of the connection. + example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: >- + The ID of the organization the connection belongs + to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - id + description: The connection with the expiring certificate. + certificate: + type: object + properties: + certificate_type: + type: string + enum: + - ResponseSigning + - RequestSigning + - ResponseEncryption + description: The type of the SAML certificate. + example: ResponseSigning + expiry_date: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + is_expired: + type: boolean + description: Whether the certificate has already expired. + example: false + required: + - certificate_type + - expiry_date + - is_expired + description: The SAML certificate details. + days_until_expiry: + type: integer + description: The number of days until the certificate expires. + example: 30 + required: + - connection + - certificate + - days_until_expiry + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: connection.saml_certificate_renewed + data: + type: object + properties: + connection: + type: object + properties: + id: + type: string + description: Unique identifier of the connection. + example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: >- + The ID of the organization the connection belongs + to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - id + description: The connection with the renewed certificate. + certificate: + type: object + properties: + certificate_type: + type: string + enum: + - ResponseSigning + - RequestSigning + - ResponseEncryption + description: The type of the SAML certificate. + example: ResponseSigning + expiry_date: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + required: + - certificate_type + - expiry_date + description: The renewed SAML certificate details. + renewed_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + required: + - connection + - certificate + - renewed_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.activated + data: + type: object + properties: + object: + type: string + description: Distinguishes the directory object. + const: directory + id: + type: string + description: Unique identifier of the directory. + example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The ID of the organization the directory belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + enum: + - azure scim v2.0 + - bamboohr + - breathe hr + - cezanne hr + - cyberark scim v2.0 + - fourth hr + - generic scim v2.0 + - gsuite directory + - gusto + - hibob + - jump cloud scim v2.0 + - okta scim v2.0 + - onelogin scim v2.0 + - people hr + - personio + - pingfederate scim v2.0 + - rippling scim v2.0 + - rippling + - sailpoint scim v2.0 + - s3 + - sftp + - sftp workday + - workday + description: The type of the directory. + example: okta scim v2.0 + state: + type: string + enum: + - active + - validating + - invalid_credentials + - inactive + - deleting + description: The current state of the directory. + example: active + name: + type: string + description: The name of the directory. + example: Acme Directory + 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' + external_key: + type: string + description: The external key of the directory. + example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHWNCE74X7JSDV0X3SZ3KJNY + domain: + type: string + description: The domain value. + example: acme.com + required: + - object + - id + - domain + description: The domains associated with the directory. + required: + - object + - id + - type + - state + - name + - created_at + - updated_at + - external_key + - domains + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.deactivated + data: + type: object + properties: + object: + type: string + description: Distinguishes the directory object. + const: directory + id: + type: string + description: Unique identifier of the directory. + example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The ID of the organization the directory belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + enum: + - azure scim v2.0 + - bamboohr + - breathe hr + - cezanne hr + - cyberark scim v2.0 + - fourth hr + - generic scim v2.0 + - gsuite directory + - gusto + - hibob + - jump cloud scim v2.0 + - okta scim v2.0 + - onelogin scim v2.0 + - people hr + - personio + - pingfederate scim v2.0 + - rippling scim v2.0 + - rippling + - sailpoint scim v2.0 + - s3 + - sftp + - sftp workday + - workday + description: The type of the directory. + example: okta scim v2.0 + state: + type: string + enum: + - active + - validating + - invalid_credentials + - inactive + - deleting + description: The current state of the directory. + example: active + name: + type: string + description: The name of the directory. + example: Acme Directory + 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' + external_key: + type: string + description: The external key of the directory. + example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHWNCE74X7JSDV0X3SZ3KJNY + domain: + type: string + description: The domain value. + example: acme.com + required: + - object + - id + - domain + description: The domains associated with the directory. + required: + - object + - id + - type + - state + - name + - created_at + - updated_at + - external_key + - domains + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the directory object. + const: directory + id: + type: string + description: Unique identifier of the directory. + example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The ID of the organization the directory belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + enum: + - azure scim v2.0 + - bamboohr + - breathe hr + - cezanne hr + - cyberark scim v2.0 + - fourth hr + - generic scim v2.0 + - gsuite directory + - gusto + - hibob + - jump cloud scim v2.0 + - okta scim v2.0 + - onelogin scim v2.0 + - people hr + - personio + - pingfederate scim v2.0 + - rippling scim v2.0 + - rippling + - sailpoint scim v2.0 + - s3 + - sftp + - sftp workday + - workday + description: The type of the directory. + example: okta scim v2.0 + state: + type: string + enum: + - active + - validating + - invalid_credentials + - inactive + - deleting + description: The current state of the directory. + example: active + name: + type: string + description: The name of the directory. + example: Acme Directory + 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 + - type + - state + - name + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.group.created + data: + $ref: '#/components/schemas/DirectoryGroup' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.group.deleted + data: + $ref: '#/components/schemas/DirectoryGroup' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.group.updated + data: + 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' + previous_attributes: + type: object + additionalProperties: {} + required: + - object + - id + - idp_id + - directory_id + - organization_id + - name + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.group.user_added + data: + type: object + properties: + directory_id: + type: string + description: The ID of the directory. + example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY + user: + $ref: '#/components/schemas/DirectoryUser' + description: The directory user added to the group. + group: + $ref: '#/components/schemas/DirectoryGroup' + description: The directory group the user was added to. + required: + - directory_id + - user + - group + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.user.created + data: + $ref: '#/components/schemas/DirectoryUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.user.deleted + data: + $ref: '#/components/schemas/DirectoryUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.group.user_removed + data: + type: object + properties: + directory_id: + type: string + description: The ID of the directory. + example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY + user: + $ref: '#/components/schemas/DirectoryUser' + description: The directory user removed from the group. + group: + $ref: '#/components/schemas/DirectoryGroup' + description: The directory group the user was removed from. + required: + - directory_id + - user + - group + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: dsync.user.updated + data: + 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: *ref_18 + 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' + previous_attributes: + type: object + additionalProperties: {} + required: + - object + - id + - directory_id + - organization_id + - idp_id + - email + - state + - raw_attributes + - custom_attributes + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: email_verification.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the email verification object. + const: email_verification + id: + type: string + description: The unique ID of the email verification code. + example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the email verification code expires. + example: '2026-01-15T12:00:00.000Z' + 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 + - user_id + - email + - expires_at + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: flag.created + data: + type: object + properties: + object: + type: string + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + environment_id: + type: string + description: The ID of the environment the Feature Flag belongs to. + example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: A descriptive name for the Feature Flag. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: >- + Labels assigned to the Feature Flag for categorizing and + filtering. + example: &ref_19 + - reports + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the + current environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't + match any configured targeting rules. + example: false + 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 + - environment_id + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + type: object + properties: + client_id: + type: string + description: The client ID associated with the flag event. + example: client_01EHWNCE74X7JSDV0X3SZ3KJNY + actor: + type: object + properties: + id: + type: string + description: Unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + source: + type: string + enum: + - api + - dashboard + - admin_portal + - system + description: The source of the actor that performed the action. + name: + type: + - string + - 'null' + description: The name of the actor. + example: Jane Doe + required: + - id + - source + - name + description: The actor who performed the action. + required: + - client_id + - actor + description: Additional context about the event. + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - context + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: flag.deleted + data: + type: object + properties: + object: + type: string + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + environment_id: + type: string + description: The ID of the environment the Feature Flag belongs to. + example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: A descriptive name for the Feature Flag. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: >- + Labels assigned to the Feature Flag for categorizing and + filtering. + example: *ref_19 + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the + current environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't + match any configured targeting rules. + example: false + 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 + - environment_id + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + type: object + properties: + client_id: + type: string + description: The client ID associated with the flag event. + example: client_01EHWNCE74X7JSDV0X3SZ3KJNY + actor: + type: object + properties: + id: + type: string + description: Unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + source: + type: string + enum: + - api + - dashboard + - admin_portal + - system + description: The source of the actor that performed the action. + name: + type: + - string + - 'null' + description: The name of the actor. + example: Jane Doe + required: + - id + - source + - name + description: The actor who performed the action. + required: + - client_id + - actor + description: Additional context about the event. + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - context + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: flag.rule_updated + data: + type: object + properties: + object: + type: string + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + environment_id: + type: string + description: The ID of the environment the Feature Flag belongs to. + example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: A descriptive name for the Feature Flag. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: >- + Labels assigned to the Feature Flag for categorizing and + filtering. + example: *ref_19 + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the + current environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't + match any configured targeting rules. + example: false + 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 + - environment_id + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + type: object + properties: + client_id: + type: string + description: The client ID associated with the flag event. + example: client_01EHWNCE74X7JSDV0X3SZ3KJNY + actor: + type: object + properties: + id: + type: string + description: Unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + source: + type: string + enum: + - api + - dashboard + - admin_portal + - system + name: + type: + - string + - 'null' + description: The name of the actor. + example: Jane Doe + required: + - id + - source + - name + description: The actor who performed the action. + access_type: + type: string + enum: + - none + - some + - all + description: The access type of the flag rule. + configured_targets: + type: object + properties: + organizations: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: The name of the organization. + example: Acme Corp + required: + - id + - name + description: The organizations targeted by the flag rule. + users: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the user. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + email: + type: string + description: The email of the user. + example: user@example.com + required: + - id + - email + description: The users targeted by the flag rule. + required: + - organizations + - users + description: The configured targets for the flag rule. + previous_attributes: + type: object + properties: + data: + type: object + properties: + enabled: + type: boolean + description: Whether the flag was previously enabled. + example: true + default_value: + type: boolean + description: The previous default value of the flag. + example: false + description: The previous data attributes of the flag. + context: + type: object + properties: + access_type: + type: string + enum: + - none + - some + - all + description: The previous access type of the flag rule. + configured_targets: + type: object + properties: + organizations: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: The name of the organization. + example: Acme Corp + required: + - id + - name + description: The organizations targeted by the flag rule. + users: + type: array + items: + type: object + properties: + id: + type: string + description: The ID of the user. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + email: + type: string + description: The email of the user. + example: user@example.com + required: + - id + - email + description: The users targeted by the flag rule. + required: + - organizations + - users + description: >- + The previous configured targets for the flag + rule. + description: The previous context attributes of the flag rule. + description: Attributes that changed from their previous values. + required: + - client_id + - actor + - access_type + - configured_targets + - previous_attributes + description: Additional context about the event. + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - context + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: flag.updated + data: + type: object + properties: + object: + type: string + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + environment_id: + type: string + description: The ID of the environment the Feature Flag belongs to. + example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: A descriptive name for the Feature Flag. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: >- + Labels assigned to the Feature Flag for categorizing and + filtering. + example: *ref_19 + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the + current environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't + match any configured targeting rules. + example: false + 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 + - environment_id + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + type: object + properties: + client_id: + type: string + description: The client ID associated with the flag event. + example: client_01EHWNCE74X7JSDV0X3SZ3KJNY + actor: + type: object + properties: + id: + type: string + description: Unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + source: + type: string + enum: + - api + - dashboard + - admin_portal + - system + description: The source of the actor that performed the action. + name: + type: + - string + - 'null' + description: The name of the actor. + example: Jane Doe + required: + - id + - source + - name + description: The actor who performed the action. + previous_attributes: + type: object + properties: + data: + type: object + properties: + name: + type: string + description: The previous name of the flag. + example: My Feature Flag + description: + type: + - string + - 'null' + description: The previous description of the flag. + example: Enables the new feature. + tags: + type: array + items: + type: string + description: The previous tags of the flag. + example: + - beta + - release + enabled: + type: boolean + description: Whether the flag was previously enabled. + example: true + default_value: + type: boolean + description: The previous default value of the flag. + example: false + description: The previous data attributes of the flag. + description: Attributes that changed from their previous values. + required: + - client_id + - actor + description: Additional context about the event. + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - context + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: group.created + data: + $ref: '#/components/schemas/Group' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: group.deleted + data: + $ref: '#/components/schemas/Group' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: group.member_added + data: + type: object + properties: + group_id: + type: string + description: The ID of the Group. + example: group_01HXYZ123456789ABCDEFGHIJ + organization_membership_id: + type: string + description: The ID of the OrganizationMembership. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - group_id + - organization_membership_id + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: group.member_removed + data: + type: object + properties: + group_id: + type: string + description: The ID of the Group. + example: group_01HXYZ123456789ABCDEFGHIJ + organization_membership_id: + type: string + description: The ID of the OrganizationMembership. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - group_id + - organization_membership_id + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: group.updated + data: + $ref: '#/components/schemas/Group' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: invitation.accepted + data: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: pending + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null + if not yet accepted. + example: null + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null + if not revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) + that the recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who invited the recipient, if + provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who accepted the invitation, once + accepted. + example: null + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on + acceptance. Reflects the current role on the invitee's + organization membership. null when the invitation has no + associated organization. + example: admin + 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 + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: invitation.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: pending + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null + if not yet accepted. + example: null + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null + if not revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) + that the recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who invited the recipient, if + provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who accepted the invitation, once + accepted. + example: null + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on + acceptance. Reflects the current role on the invitee's + organization membership. null when the invitation has no + associated organization. + example: admin + 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 + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: invitation.resent + data: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: pending + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null + if not yet accepted. + example: null + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null + if not revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) + that the recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who invited the recipient, if + provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who accepted the invitation, once + accepted. + example: null + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on + acceptance. Reflects the current role on the invitee's + organization membership. null when the invitation has no + associated organization. + example: admin + 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 + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: invitation.revoked + data: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: pending + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null + if not yet accepted. + example: null + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null + if not revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) + that the recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who invited the recipient, if + provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: >- + The ID of the user who accepted the invitation, once + accepted. + example: null + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on + acceptance. Reflects the current role on the invitee's + organization membership. null when the invitation has no + associated organization. + example: admin + 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 + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: magic_auth.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the Magic Auth object. + const: magic_auth + id: + type: string + description: The unique ID of the Magic Auth code. + example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the Magic Auth code expires. + example: '2026-01-15T12:00:00.000Z' + 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 + - user_id + - email + - expires_at + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the Organization object. + const: organization + id: + type: string + description: Unique identifier of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: >- + A descriptive name for the Organization. This field does + not need to be unique. + example: Acme Inc. + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: List of Organization Domains. + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 + description: >- + Object containing [metadata](/authkit/metadata) + key/value pairs associated with the Organization. + example: &ref_20 + tier: diamond + propertyNames: + maxLength: 40 + maxProperties: 50 + external_id: + type: + - string + - 'null' + description: The external ID of the Organization. + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + stripe_customer_id: + type: string + description: The Stripe customer ID of the Organization. + example: cus_R9qWAGMQ6nGE7V + 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 + - name + - domains + - metadata + - external_id + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the Organization object. + const: organization + id: + type: string + description: Unique identifier of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: >- + A descriptive name for the Organization. This field does + not need to be unique. + example: Acme Inc. + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: List of Organization Domains. + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 + description: >- + Object containing [metadata](/authkit/metadata) + key/value pairs associated with the Organization. + example: *ref_20 + propertyNames: + maxLength: 40 + maxProperties: 50 + external_id: + type: + - string + - 'null' + description: The external ID of the Organization. + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + stripe_customer_id: + type: string + description: The Stripe customer ID of the Organization. + example: cus_R9qWAGMQ6nGE7V + 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 + - name + - domains + - metadata + - external_id + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_domain.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_domain.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_domain.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_domain.verification_failed + data: + type: object + properties: + reason: + type: string + enum: + - domain_verification_period_expired + - domain_verified_by_other_organization + description: The reason the domain verification failed. + example: domain_verification_period_expired + organization_domain: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: The organization domain that failed verification. + required: + - reason + - organization_domain + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_domain.verified + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_membership.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: Unique identifier of the organization membership. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + user_id: + type: string + description: The ID of the user. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + status: + type: string + enum: + - active + - inactive + - pending + description: The status of the organization membership. + example: active + role: + $ref: '#/components/schemas/SlimRole' + description: The role associated with the membership. + roles: + type: array + items: + $ref: '#/components/schemas/SlimRole' + description: The roles associated with the membership. + custom_attributes: + type: object + additionalProperties: {} + description: Custom attributes associated with the membership. + directory_managed: + type: boolean + description: >- + Whether the membership is managed by a directory sync + provider. + example: false + 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 + - user_id + - organization_id + - status + - role + - custom_attributes + - directory_managed + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_membership.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: Unique identifier of the organization membership. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + user_id: + type: string + description: The ID of the user. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + status: + type: string + enum: + - active + - inactive + - pending + description: The status of the organization membership. + example: active + role: + $ref: '#/components/schemas/SlimRole' + description: The role associated with the membership. + roles: + type: array + items: + $ref: '#/components/schemas/SlimRole' + description: The roles associated with the membership. + custom_attributes: + type: object + additionalProperties: {} + description: Custom attributes associated with the membership. + directory_managed: + type: boolean + description: >- + Whether the membership is managed by a directory sync + provider. + example: false + 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 + - user_id + - organization_id + - status + - role + - custom_attributes + - directory_managed + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_membership.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: Unique identifier of the organization membership. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + user_id: + type: string + description: The ID of the user. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The ID of the organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + status: + type: string + enum: + - active + - inactive + - pending + description: The status of the organization membership. + example: active + role: + $ref: '#/components/schemas/SlimRole' + description: The role associated with the membership. + roles: + type: array + items: + $ref: '#/components/schemas/SlimRole' + description: The roles associated with the membership. + custom_attributes: + type: object + additionalProperties: {} + description: Custom attributes associated with the membership. + directory_managed: + type: boolean + description: >- + Whether the membership is managed by a directory sync + provider. + example: false + 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 + - user_id + - organization_id + - status + - role + - custom_attributes + - directory_managed + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_role.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization role object. + const: organization_role + organization_id: + type: string + description: The ID of the organization the role belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: The slug identifier of the role. + example: billing-admin + name: + type: string + description: The name of the role. + example: Billing Administrator + description: + type: + - string + - 'null' + description: A description of the role. + example: Can manage billing settings. + resource_type_slug: + type: string + description: The slug of the resource type the role applies to. + example: organization + permissions: + type: array + items: + type: string + description: The permissions granted by the role. + example: &ref_21 + - users:read + - users: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 + - organization_id + - slug + - name + - description + - resource_type_slug + - permissions + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_role.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization role object. + const: organization_role + organization_id: + type: string + description: The ID of the organization the role belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: The slug identifier of the role. + example: billing-admin + name: + type: string + description: The name of the role. + example: Billing Administrator + description: + type: + - string + - 'null' + description: A description of the role. + example: Can manage billing settings. + resource_type_slug: + type: string + description: The slug of the resource type the role applies to. + example: organization + permissions: + type: array + items: + type: string + description: The permissions granted by the role. + example: *ref_21 + 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 + - organization_id + - slug + - name + - description + - resource_type_slug + - permissions + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization_role.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the organization role object. + const: organization_role + organization_id: + type: string + description: The ID of the organization the role belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: The slug identifier of the role. + example: billing-admin + name: + type: string + description: The name of the role. + example: Billing Administrator + description: + type: + - string + - 'null' + description: A description of the role. + example: Can manage billing settings. + resource_type_slug: + type: string + description: The slug of the resource type the role applies to. + example: organization + permissions: + type: array + items: + type: string + description: The permissions granted by the role. + example: *ref_21 + 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 + - organization_id + - slug + - name + - description + - resource_type_slug + - permissions + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: organization.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the Organization object. + const: organization + id: + type: string + description: Unique identifier of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: >- + A descriptive name for the Organization. This field does + not need to be unique. + example: Acme Inc. + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: List of Organization Domains. + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 + description: >- + Object containing [metadata](/authkit/metadata) + key/value pairs associated with the Organization. + example: *ref_20 + propertyNames: + maxLength: 40 + maxProperties: 50 + external_id: + type: + - string + - 'null' + description: The external ID of the Organization. + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + stripe_customer_id: + type: string + description: The Stripe customer ID of the Organization. + example: cus_R9qWAGMQ6nGE7V + 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 + - name + - domains + - metadata + - external_id + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: password_reset.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the password reset object. + const: password_reset + id: + type: string + description: The unique ID of the password reset object. + example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the password reset token expires. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: The timestamp when the password reset token was created. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - user_id + - email + - expires_at + - created_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: password_reset.succeeded + data: + type: object + properties: + object: + type: string + description: Distinguishes the password reset object. + const: password_reset + id: + type: string + description: The unique ID of the password reset object. + example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the password reset token expires. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: The timestamp when the password reset token was created. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - user_id + - email + - expires_at + - created_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: permission.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the permission object. + const: permission + id: + type: string + description: Unique identifier of the permission. + example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: The slug identifier of the permission. + example: billing:manage + name: + type: string + description: The name of the permission. + example: Manage Billing + description: + type: + - string + - 'null' + description: A description of the permission. + example: Allows managing billing settings. + system: + type: boolean + description: Whether the permission is a system permission. + example: false + 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 + - slug + - name + - description + - system + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: permission.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the permission object. + const: permission + id: + type: string + description: Unique identifier of the permission. + example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: The slug identifier of the permission. + example: billing:manage + name: + type: string + description: The name of the permission. + example: Manage Billing + description: + type: + - string + - 'null' + description: A description of the permission. + example: Allows managing billing settings. + system: + type: boolean + description: Whether the permission is a system permission. + example: false + 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 + - slug + - name + - description + - system + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: permission.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the permission object. + const: permission + id: + type: string + description: Unique identifier of the permission. + example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY + slug: + type: string + description: The slug identifier of the permission. + example: billing:manage + name: + type: string + description: The name of the permission. + example: Manage Billing + description: + type: + - string + - 'null' + description: A description of the permission. + example: Allows managing billing settings. + system: + type: boolean + description: Whether the permission is a system permission. + example: false + 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 + - slug + - name + - description + - system + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: role.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the role object. + const: role + slug: + type: string + description: The slug identifier of the role. + example: admin + resource_type_slug: + type: string + description: The slug of the resource type the role applies to. + example: organization + permissions: + type: array + items: + type: string + description: The permissions granted by the role. + example: &ref_22 + - users:read + - users: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 + - slug + - resource_type_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: role.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the role object. + const: role + slug: + type: string + description: The slug identifier of the role. + example: admin + resource_type_slug: + type: string + description: The slug of the resource type the role applies to. + example: organization + permissions: + type: array + items: + type: string + description: The permissions granted by the role. + example: *ref_22 + 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 + - slug + - resource_type_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: role.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the role object. + const: role + slug: + type: string + description: The slug identifier of the role. + example: admin + resource_type_slug: + type: string + description: The slug of the resource type the role applies to. + example: organization + permissions: + type: array + items: + type: string + description: The permissions granted by the role. + example: *ref_22 + 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 + - slug + - resource_type_slug + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: session.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the session object. + const: session + id: + type: string + description: The unique ID of the session. + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + impersonator: + type: object + properties: + email: + type: string + description: >- + The email address of the WorkOS Dashboard user who + is impersonating the user. + example: admin@foocorp.com + reason: + type: + - string + - 'null' + description: >- + The justification the impersonator gave for + impersonating the user. + example: Investigating an issue with the customer's account. + required: + - email + - reason + description: >- + Information about the impersonator if this session was + created via impersonation. + ip_address: + type: + - string + - 'null' + description: The IP address from which the session was created. + example: 198.51.100.42 + organization_id: + type: string + description: >- + The ID of the organization this session is associated + with. + example: org_01H945H0YD4F97JN9MATX7BYAG + user_agent: + type: + - string + - 'null' + description: >- + The user agent string from the device that created the + session. + example: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 + user_id: + type: string + description: The ID of the user this session belongs to. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + auth_method: + type: string + enum: + - cross_app_auth + - external_auth + - impersonation + - magic_code + - migrated_session + - oauth + - passkey + - password + - sso + - unknown + description: The authentication method used to create this session. + example: sso + status: + type: string + enum: + - active + - expired + - revoked + description: The current status of the session. + example: active + expires_at: + format: date-time + type: string + description: The timestamp when the session expires. + example: '2026-01-15T12:00:00.000Z' + ended_at: + format: date-time + type: + - string + - 'null' + description: The timestamp when the session ended. + example: null + 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 + - ip_address + - user_agent + - user_id + - auth_method + - status + - expires_at + - ended_at + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: session.revoked + data: + type: object + properties: + object: + type: string + description: Distinguishes the session object. + const: session + id: + type: string + description: The unique ID of the session. + example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 + impersonator: + type: object + properties: + email: + type: string + description: >- + The email address of the WorkOS Dashboard user who + is impersonating the user. + example: admin@foocorp.com + reason: + type: + - string + - 'null' + description: >- + The justification the impersonator gave for + impersonating the user. + example: Investigating an issue with the customer's account. + required: + - email + - reason + description: >- + Information about the impersonator if this session was + created via impersonation. + ip_address: + type: + - string + - 'null' + description: The IP address from which the session was created. + example: 198.51.100.42 + organization_id: + type: string + description: >- + The ID of the organization this session is associated + with. + example: org_01H945H0YD4F97JN9MATX7BYAG + user_agent: + type: + - string + - 'null' + description: >- + The user agent string from the device that created the + session. + example: >- + Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) + AppleWebKit/537.36 + user_id: + type: string + description: The ID of the user this session belongs to. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + auth_method: + type: string + enum: + - cross_app_auth + - external_auth + - impersonation + - magic_code + - migrated_session + - oauth + - passkey + - password + - sso + - unknown + description: The authentication method used to create this session. + example: sso + status: + type: string + enum: + - active + - expired + - revoked + description: The current status of the session. + example: active + expires_at: + format: date-time + type: string + description: The timestamp when the session expires. + example: '2026-01-15T12:00:00.000Z' + ended_at: + format: date-time + type: + - string + - 'null' + description: The timestamp when the session ended. + example: null + 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 + - ip_address + - user_agent + - user_id + - auth_method + - status + - expires_at + - ended_at + - created_at + - updated_at + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: user.created + data: + $ref: '#/components/schemas/UserlandUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: user.deleted + data: + $ref: '#/components/schemas/UserlandUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: user.updated + data: + $ref: '#/components/schemas/UserlandUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.byok_key.deleted + data: + type: object + properties: + organization_id: + type: string + description: The unique identifier of the organization. + example: org_01EHT88Z8J8795GZNQ4ZP1J81T + key_provider: + type: string + enum: + - AWS_KMS + - GCP_KMS + - AZURE_KEY_VAULT + description: The external key provider used for BYOK. + example: AWS_KMS + required: + - organization_id + - key_provider + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.byok_key.verification_completed + data: + type: object + properties: + organization_id: + type: string + description: The unique identifier of the organization. + example: org_01EHT88Z8J8795GZNQ4ZP1J81T + key_provider: + type: string + enum: + - AWS_KMS + - GCP_KMS + - AZURE_KEY_VAULT + description: The external key provider used for BYOK. + example: AWS_KMS + verified: + type: boolean + description: >- + Whether the BYOK key verification completed + successfully. + example: true + required: + - organization_id + - key_provider + - verified + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.data.created + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + kv_name: + type: string + description: The name of the key-value store. + example: user-secrets + key_id: + type: string + description: The unique identifier of the encryption key. + example: key_01EHWNCE74X7JSDV0X3SZ3KJNY + key_context: + type: object + additionalProperties: + type: string + required: + - actor_id + - actor_source + - actor_name + - kv_name + - key_id + - key_context + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.data.deleted + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + kv_name: + type: string + description: The name of the key-value store. + example: user-secrets + required: + - actor_id + - actor_source + - actor_name + - kv_name + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.data.read + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + kv_name: + type: string + description: The name of the key-value store. + example: user-secrets + key_id: + type: string + description: The unique identifier of the encryption key. + example: key_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - actor_id + - actor_source + - actor_name + - kv_name + - key_id + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.data.updated + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + kv_name: + type: string + description: The name of the key-value store. + example: user-secrets + key_id: + type: string + description: The unique identifier of the encryption key. + example: key_01EHWNCE74X7JSDV0X3SZ3KJNY + key_context: + type: object + additionalProperties: + type: string + required: + - actor_id + - actor_source + - actor_name + - kv_name + - key_id + - key_context + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.dek.decrypted + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + key_id: + type: string + description: The unique identifier of the data encryption key. + example: key_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - actor_id + - actor_source + - actor_name + - key_id + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.dek.read + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + key_ids: + type: array + items: + type: string + description: The unique identifiers of the data encryption keys. + example: + - dek_01EHWNCE74X7JSDV0X3SZ3KJNY + key_context: + type: object + additionalProperties: + type: string + required: + - actor_id + - actor_source + - actor_name + - key_ids + - key_context + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.kek.created + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + key_name: + type: string + description: The name of the key encryption key. + example: production-kek + key_id: + type: string + description: The unique identifier of the key encryption key. + example: key_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - actor_id + - actor_source + - actor_name + - key_name + - key_id + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.metadata.read + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + kv_name: + type: string + description: The name of the key-value store. + example: user-secrets + required: + - actor_id + - actor_source + - actor_name + - kv_name + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: vault.names.listed + data: + type: object + properties: + actor_id: + type: string + description: The unique identifier of the actor. + example: user_01EHWNCE74X7JSDV0X3SZ3KJNY + actor_source: + type: string + enum: + - api + - dashboard + actor_name: + type: string + description: The name of the actor. + example: Jane Doe + required: + - actor_id + - actor_source + - actor_name + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: waitlist_user.approved + data: + $ref: '#/components/schemas/WaitlistUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: waitlist_user.created + data: + $ref: '#/components/schemas/WaitlistUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + - type: object + properties: + id: + type: string + description: Unique identifier for the event. + example: event_01EHZNVPK3SFK441A1RGBFSHRT + event: + type: string + const: waitlist_user.denied + data: + $ref: '#/components/schemas/WaitlistUser' + description: The event payload. + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + context: + $ref: '#/components/schemas/EventContextDto' + object: + type: string + description: Distinguishes the Event object. + const: event + required: + - id + - event + - data + - created_at + - object + example: *ref_23 + description: An event emitted by WorkOS. + EventList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/EventSchema' + description: The list of records for the current page. + list_metadata: + type: object + properties: + 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: event_01EHZNVPK3SFK441A1RGBFSHRT + required: + - after + description: Pagination cursor for navigating to the next page of results. + required: + - object + - data + - list_metadata + example: + object: list + data: + - *ref_23 + list_metadata: + after: event_01EHZNVPK3SFK441A1RGBFSHRT + JwtTemplate: + type: object + properties: + object: + type: string + description: The object type. + const: jwt_template + content: + type: string + description: The JWT template content as a Liquid template string. + example: >- + {"urn:myapp:full_name": "{{user.first_name}} {{user.last_name}}", + "urn:myapp:email": "{{user.email}}"} + created_at: + type: string + description: The timestamp when the JWT template was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the JWT template was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - content + - created_at + - updated_at + OrganizationDomainStandAlone: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + Flag: + type: object + properties: + object: + type: string + description: Distinguishes the Feature Flag object. + const: feature_flag + id: + type: string + description: Unique identifier of the Feature Flag. + example: flag_01EHZNVPK3SFK441A1RGBFSHRT + slug: + type: string + description: A unique key to reference the Feature Flag. + example: advanced-analytics + name: + type: string + description: >- + A descriptive name for the Feature Flag. This field does not need to + be unique. + example: Advanced Analytics + description: + type: + - string + - 'null' + description: A description for the Feature Flag. + example: Enable advanced analytics dashboard feature + owner: + description: The owner of the Feature Flag. + oneOf: + - type: object + properties: + email: + type: string + description: The email address of the flag owner. + example: jane@example.com + first_name: + type: + - string + - 'null' + description: The first name of the flag owner. + example: Jane + last_name: + type: + - string + - 'null' + description: The last name of the flag owner. + example: Doe + required: + - email + - first_name + - last_name + - type: 'null' + tags: + type: array + items: + type: string + description: Labels assigned to the Feature Flag for categorizing and filtering. + example: + - reports + enabled: + type: boolean + description: >- + Specifies whether the Feature Flag is active for the current + environment. + example: true + default_value: + type: boolean + description: >- + The value returned for users and organizations who don't match any + configured targeting rules. + example: false + 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 + - slug + - name + - description + - owner + - tags + - enabled + - default_value + - created_at + - updated_at + FlagList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Flag' + 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: flag_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: flag_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + OrganizationApiKey: + 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: organization + const: organization + id: + type: string + description: Unique identifier of the API Key owner. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - type + - 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 + OrganizationApiKeyList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/OrganizationApiKey' + 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 + OrganizationApiKeyWithValue: + 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: organization + const: organization + id: + type: string + description: Unique identifier of the API Key owner. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + required: + - type + - 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 + Organization: + type: object + properties: + object: + type: string + description: Distinguishes the Organization object. + const: organization + id: + type: string + description: Unique identifier of the Organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: >- + A descriptive name for the Organization. This field does not need to + be unique. + example: Acme Inc. + domains: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the organization domain object. + const: organization_domain + id: + type: string + description: Unique identifier of the organization domain. + example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A + organization_id: + type: string + description: ID of the parent Organization. + example: org_01HE8GSH8FQPASKSY27THRKRBP + domain: + type: string + description: Domain for the organization domain. + example: foo-corp.com + state: + type: string + enum: + - failed + - legacy_verified + - pending + - unverified + - verified + description: Verification state of the domain. + example: pending + verification_prefix: + type: string + description: The prefix used in DNS verification. + example: superapp-domain-verification-z3kjny + verification_token: + type: string + description: Validation token to be used in DNS TXT record. + example: m5Oztg3jdK4NJLgs8uIlIprMw + verification_strategy: + type: string + enum: + - dns + - manual + description: Strategy used to verify the domain. + example: dns + 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 + - organization_id + - domain + - created_at + - updated_at + description: List of Organization Domains. + metadata: + type: object + additionalProperties: + type: string + maxLength: 600 + description: >- + Object containing [metadata](/authkit/metadata) key/value pairs + associated with the Organization. + example: + tier: diamond + propertyNames: + maxLength: 40 + maxProperties: 50 + external_id: + type: + - string + - 'null' + description: The external ID of the Organization. + example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 + stripe_customer_id: + type: string + description: The Stripe customer ID of the Organization. + example: cus_R9qWAGMQ6nGE7V + 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' + allow_profiles_outside_organization: + type: boolean + description: >- + Whether the Organization allows profiles outside of its managed + domains. + example: false + deprecated: true + required: + - object + - id + - name + - domains + - metadata + - external_id + - created_at + - updated_at + OrganizationList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/Organization' + 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: org_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: org_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + - list_metadata + AuditLogConfiguration: + type: object + properties: + organization_id: + type: string + description: Unique identifier of the Organization. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + retention_period_in_days: + type: integer + description: >- + The number of days Audit Log events will be retained before being + permanently deleted. + example: 30 + state: + type: string + enum: + - active + - inactive + - disabled + description: >- + The current state of the audit log configuration for the + organization. + example: active + log_stream: + type: object + properties: + id: + type: string + description: Unique identifier of the Audit Log Stream. + example: als_01EHZNVPK3SFK441A1RGBFSHRT + type: + type: string + enum: + - AzureSentinel + - Datadog + - GenericHttps + - GoogleCloudStorage + - S3 + - Splunk + description: The type of the Audit Log Stream destination. + example: Datadog + state: + type: string + enum: + - active + - inactive + - error + - invalid + description: The current state of the Audit Log Stream. + example: active + last_synced_at: + type: + - string + - 'null' + description: >- + ISO-8601 timestamp of when the last event was successfully + synced, or null if no events have been synced. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: An ISO 8601 timestamp. + example: '2026-01-15T12:00:00.000Z' + required: + - id + - type + - state + - last_synced_at + - created_at + description: >- + The Audit Log Stream currently configured for the organization, if + any. + required: + - organization_id + - retention_period_in_days + - state + DataIntegrationAuthorizeUrlResponse: + type: object + properties: + url: + type: string + description: The OAuth authorization URL to redirect the user to. + example: >- + https://api.workos.com/data-integrations/q2czJKmVAraSBg8xFpT7M9uR/authorize-redirect + required: + - url + DataIntegrationAccessTokenResponse: + oneOf: + - type: object + properties: + active: + type: boolean + description: >- + Indicates whether the access token is valid and ready for use, + or if reauthorization is required. + const: true + access_token: + type: object + properties: + object: + type: string + description: Distinguishes the access token object. + const: access_token + access_token: + type: string + description: The OAuth access token for the connected integration. + example: gho_16C7e42F292c6912E7710c838347Ae178B4a + expires_at: + type: + - string + - 'null' + description: >- + The ISO-8601 formatted timestamp indicating when the access + token expires. + example: '2025-12-31T23:59:59.000Z' + scopes: + type: array + items: + type: string + description: The scopes granted to the access token. + example: + - repo + - user:email + missing_scopes: + type: array + items: + type: string + description: >- + If the integration has requested scopes that aren't present + on the access token, they're listed here. + example: [] + required: + - object + - access_token + - expires_at + - scopes + - missing_scopes + description: >- + The [access token](/reference/pipes/access-token) object, + present when `active` is `true`. + required: + - active + - access_token + - type: object + properties: + active: + type: boolean + description: >- + Indicates whether the access token is valid and ready for use, + or if reauthorization is required. + const: false + error: + type: string + enum: + - needs_reauthorization + - not_installed + description: >- + - `"not_installed"`: The user does not have the integration + installed. + + - `"needs_reauthorization"`: The user needs to reauthorize the + integration. + example: not_installed + required: + - active + - error + ConnectedAccount: + type: object + properties: + object: + type: string + description: Distinguishes the connected account object. + const: connected_account + id: + type: string + description: The unique identifier of the connected account. + example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT + user_id: + type: + - string + - 'null' + description: >- + The [User](/reference/authkit/user) identifier associated with this + connection. + example: user_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: + - string + - 'null' + description: >- + The [Organization](/reference/organization) identifier associated + with this connection, or `null` if not scoped to an organization. + example: null + scopes: + type: array + items: + type: string + description: The OAuth scopes granted for this connection. + example: + - repo + - user:email + state: + type: string + enum: + - connected + - needs_reauthorization + - disconnected + description: >- + The state of the connected account: + + - `connected`: The connection is active and tokens are valid. + + - `needs_reauthorization`: The user needs to reauthorize the + connection, typically because required scopes have changed. + + - `disconnected`: The connection has been disconnected. + example: connected + created_at: + type: string + description: The timestamp when the connection was created. + example: '2024-01-16T14:20:00.000Z' + updated_at: + type: string + description: The timestamp when the connection was last updated. + example: '2024-01-16T14:20:00.000Z' + required: + - object + - id + - user_id + - organization_id + - scopes + - state + - created_at + - updated_at + DataIntegrationsListResponse: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + type: object + properties: + object: + type: string + description: Distinguishes the data provider object. + const: data_provider + id: + type: string + description: The unique identifier of the provider. + example: data_integration_01EHZNVPK3SFK441A1RGBFSHRT + name: + type: string + description: The display name of the provider (e.g., "GitHub", "Slack"). + example: GitHub + description: + type: + - string + - 'null' + description: >- + A description of the provider explaining how it will be used, + if configured. + example: Connect your GitHub account to access repositories. + slug: + type: string + description: >- + The slug identifier used in API calls (e.g., `github`, + `slack`, `notion`). + example: github + integration_type: + type: string + description: The type of integration (e.g., `github`, `slack`). + example: github + credentials_type: + type: string + description: The type of credentials used by the provider (e.g., `oauth2`). + example: oauth2 + scopes: + description: >- + The OAuth scopes configured for this provider, or `null` if + none are configured. + example: + - repo + - user:email + oneOf: + - type: array + items: + type: string + - type: 'null' + ownership: + type: string + enum: + - userland_user + - organization + description: Whether the provider is owned by a user or organization. + created_at: + type: string + description: The timestamp when the provider was created. + example: '2024-01-15T10:30:00.000Z' + updated_at: + type: string + description: The timestamp when the provider was last updated. + example: '2024-01-15T10:30:00.000Z' + integrationType: + type: string + deprecated: true + description: Use integration_type instead. + credentialsType: + type: string + deprecated: true + description: Use credentials_type instead. + createdAt: + type: string + deprecated: true + description: Use created_at instead. + updatedAt: + type: string + deprecated: true + description: Use updated_at instead. + connected_account: + description: >- + The user's [connected + account](/reference/pipes/connected-account) for this + provider, or `null` if the user has not connected. + oneOf: + - type: object + properties: + object: + type: string + description: Distinguishes the connected account object. + const: connected_account + id: + type: string + description: The unique identifier of the connected account. + example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT + user_id: + type: + - string + - 'null' + description: >- + The [User](/reference/authkit/user) identifier + associated with this connection. + example: user_01EHZNVPK3SFK441A1RGBFSHRT + organization_id: + type: + - string + - 'null' + description: >- + The [Organization](/reference/organization) identifier + associated with this connection, or `null` if not + scoped to an organization. + example: null + scopes: + type: array + items: + type: string + description: The OAuth scopes granted for this connection. + example: + - repo + - user:email + state: + type: string + enum: + - connected + - needs_reauthorization + - disconnected + description: >- + The state of the connected account: + + - `connected`: The connection is active and tokens are + valid. + + - `needs_reauthorization`: The user needs to + reauthorize the connection, typically because required + scopes have changed. + + - `disconnected`: The connection has been + disconnected. + example: connected + created_at: + type: string + description: The timestamp when the connection was created. + example: '2024-01-16T14:20:00.000Z' + updated_at: + type: string + description: The timestamp when the connection was last updated. + example: '2024-01-16T14:20:00.000Z' + userlandUserId: + type: + - string + - 'null' + deprecated: true + description: Use `user_id` instead. + organizationId: + type: + - string + - 'null' + deprecated: true + description: Use `organization_id` instead. + createdAt: + type: string + deprecated: true + description: Use `created_at` instead. + updatedAt: + type: string + deprecated: true + description: Use `updated_at` instead. + required: + - object + - id + - user_id + - organization_id + - scopes + - state + - created_at + - updated_at + - userlandUserId + - organizationId + - createdAt + - updatedAt + - type: 'null' + required: + - object + - id + - name + - description + - slug + - integration_type + - credentials_type + - scopes + - ownership + - created_at + - updated_at + - integrationType + - credentialsType + - createdAt + - updatedAt + - connected_account + description: >- + A list of [providers](/reference/pipes/provider), each including a + [`connected_account`](/reference/pipes/connected-account) field with + the user's connection status. + required: + - object + - data + PortalLinkResponse: + type: object + properties: + link: + type: string + description: An ephemeral link to initiate the Admin Portal. + example: >- + https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... + required: + - link + RadarStandaloneResponse: + type: object + properties: + verdict: + type: string + enum: + - allow + - block + - challenge + description: The verdict of the risk assessment. + example: block + reason: + type: string + description: A human-readable reason for the verdict. + example: Detected enabled Radar control + attempt_id: + type: string + description: Unique identifier of the authentication attempt. + example: radar_att_01HZBC6N1EB1ZY7KG32X + control: + type: string + enum: + - bot_detection + - brute_force_attack + - credential_stuffing + - domain_sign_up_rate_limit + - ip_sign_up_rate_limit + - impossible_travel + - repeat_sign_up + - stale_account + - unrecognized_device + - restriction + description: >- + The Radar control that triggered the verdict. Only present if the + verdict is `block` or `challenge`. + example: bot_detection + blocklist_type: + type: string + enum: + - ip_address + - domain + - email + - device + - user_agent + - device_fingerprint + - country + description: >- + The type of blocklist entry that triggered the verdict. Only present + if the control is `restriction`. + example: ip_address + required: + - verdict + - reason + - attempt_id + RadarListEntryAlreadyPresentResponse: + type: object + properties: + message: + type: string + description: A message indicating the entry already exists. + example: Entry already present in list + required: + - message + RedirectUri: + type: object + properties: + object: + type: string + description: The object type. + const: redirect_uri + id: + type: string + description: The ID of the redirect URI. + example: ruri_01EHZNVPK3SFK441A1RGBFSHRT + uri: + type: string + description: The redirect URI. + example: https://example.com/callback + default: + type: boolean + description: Whether this is the default redirect URI. + example: true + created_at: + type: string + description: The timestamp when the redirect URI was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the redirect URI was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - uri + - default + - created_at + - updated_at + UserlandUserAuthenticationFactorList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/AuthenticationFactor' + 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: auth_factor_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: auth_factor_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + UserlandUserAuthenticationFactorEnrollResponse: + type: object + properties: + authentication_factor: + $ref: '#/components/schemas/AuthenticationFactorEnrolled' + description: >- + The [authentication + factor](/reference/authkit/mfa/authentication-factor) object that + represents the additional authentication method used on top of the + existing authentication strategy. + authentication_challenge: + $ref: '#/components/schemas/AuthenticationChallenge' + description: >- + The [authentication + challenge](/reference/authkit/mfa/authentication-challenge) object + that is used to complete the authentication process. + required: + - authentication_factor + - authentication_challenge + MagicAuth: + type: object + properties: + object: + type: string + description: Distinguishes the Magic Auth object. + const: magic_auth + id: + type: string + description: The unique ID of the Magic Auth code. + example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the Magic Auth code expires. + example: '2026-01-15T12:00:00.000Z' + 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' + code: + type: string + description: The code used to verify the Magic Auth code. + example: '123456' + required: + - object + - id + - user_id + - email + - expires_at + - created_at + - updated_at + - code + UserlandUserInvite: + type: object + properties: + object: + type: string + description: Distinguishes the invitation object. + const: invitation + id: + type: string + description: The unique ID of the invitation. + example: invitation_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the recipient. + example: marcelina.davis@example.com + state: + type: string + enum: + - pending + - accepted + - expired + - revoked + description: The state of the invitation. + example: pending + accepted_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was accepted, or null if not yet + accepted. + example: null + revoked_at: + format: date-time + type: + - string + - 'null' + description: >- + The timestamp when the invitation was revoked, or null if not + revoked. + example: null + expires_at: + format: date-time + type: string + description: The timestamp when the invitation expires. + example: '2026-01-15T12:00:00.000Z' + organization_id: + type: + - string + - 'null' + description: >- + The ID of the [organization](/reference/organization) that the + recipient will join. + example: org_01E4ZCR3C56J083X43JQXF3JK5 + inviter_user_id: + type: + - string + - 'null' + description: The ID of the user who invited the recipient, if provided. + example: user_01HYGBX8ZGD19949T3BM4FW1C3 + accepted_user_id: + type: + - string + - 'null' + description: The ID of the user who accepted the invitation, once accepted. + example: null + role_slug: + type: + - string + - 'null' + description: >- + Slug of the role the invitee will be assigned on acceptance. + Reflects the current role on the invitee's organization membership. + null when the invitation has no associated organization. + example: admin + 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' + token: + type: string + description: The token used to accept the invitation. + example: Z1uX3RbwcIl5fIGJJJCXXisdI + accept_invitation_url: + type: string + description: The URL where the recipient can accept the invitation. + example: >- + https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI + required: + - object + - id + - email + - state + - accepted_at + - revoked_at + - expires_at + - organization_id + - inviter_user_id + - accepted_user_id + - role_slug + - created_at + - updated_at + - token + - accept_invitation_url + UserlandUserOrganizationMembership: + type: object + properties: + object: + type: string + description: Distinguishes the organization membership object. + const: organization_membership + id: + type: string + description: The unique ID of the organization membership. + example: om_01HXYZ123456789ABCDEFGHIJ + user_id: + type: string + description: The ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + organization_id: + type: string + description: The ID of the organization which the user belongs to. + example: org_01EHZNVPK3SFK441A1RGBFSHRT + status: + type: string + enum: + - active + - inactive + - pending + description: >- + The status of the organization membership. One of `active`, + `inactive`, or `pending`. + example: active + directory_managed: + type: boolean + description: >- + Whether this organization membership is managed by a directory sync + connection. + example: false + organization_name: + type: string + description: The name of the organization which the user belongs to. + example: Acme Corp + custom_attributes: + type: object + additionalProperties: {} + description: >- + An object containing IdP-sourced attributes from the linked + [Directory User](/reference/directory-sync/directory-user) or [SSO + Profile](/reference/sso/profile). Directory User attributes take + precedence when both are linked. + example: + department: Engineering + title: Developer Experience Engineer + location: Brooklyn + 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' + role: + $ref: '#/components/schemas/SlimRole' + description: The primary role assigned to the user within the organization. + user: + $ref: '#/components/schemas/UserlandUser' + description: The user that belongs to the organization through this membership. + required: + - object + - id + - user_id + - organization_id + - status + - directory_managed + - created_at + - updated_at + - role + - user + 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 + 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 + 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 + UserlandUserList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/UserlandUser' + 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: 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: user_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + EmailVerification: + type: object + properties: + object: + type: string + description: Distinguishes the email verification object. + const: email_verification + id: + type: string + description: The unique ID of the email verification code. + example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the email verification code expires. + example: '2026-01-15T12:00:00.000Z' + 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' + code: + type: string + description: The code used to verify the email. + example: '123456' + required: + - object + - id + - user_id + - email + - expires_at + - created_at + - updated_at + - code + SendVerificationEmailResponse: + type: object + properties: + user: + $ref: '#/components/schemas/UserlandUser' + description: The user to whom the verification email was sent. + required: + - user + VerifyEmailResponse: + type: object + properties: + user: + $ref: '#/components/schemas/UserlandUser' + description: The user whose email was verified. + required: + - user + PasswordReset: + type: object + properties: + object: + type: string + description: Distinguishes the password reset object. + const: password_reset + id: + type: string + description: The unique ID of the password reset object. + example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 + user_id: + type: string + description: The unique ID of the user. + example: user_01E4ZCR3C56J083X43JQXF3JK5 + email: + type: string + description: The email address of the user. + example: marcelina.davis@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the password reset token expires. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: The timestamp when the password reset token was created. + example: '2026-01-15T12:00:00.000Z' + password_reset_token: + type: string + description: The token used to reset the password. + example: Z1uX3RbwcIl5fIGJJJCXXisdI + password_reset_url: + type: string + description: The URL where the user can reset their password. + example: https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI + required: + - object + - id + - user_id + - email + - expires_at + - created_at + - password_reset_token + - password_reset_url + ResetPasswordResponse: + type: object + properties: + user: + $ref: '#/components/schemas/UserlandUser' + description: The user whose password was reset. + required: + - user + EmailChange: + type: object + properties: + object: + type: string + description: Distinguishes the email change object. + const: email_change + user: + $ref: '#/components/schemas/UserlandUser' + new_email: + type: string + description: The new email address the user is changing to. + example: new.email@example.com + expires_at: + format: date-time + type: string + description: The timestamp when the email change code expires. + example: '2026-01-15T12:00:00.000Z' + created_at: + format: date-time + type: string + description: The timestamp when the email change challenge was created. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - user + - new_email + - expires_at + - created_at + UserlandAuthenticateResponse: + type: object + properties: + user: + $ref: '#/components/schemas/UserlandUser' + description: The corresponding [user](/reference/authkit/user) object. + organization_id: + type: string + description: The ID of the organization the user selected to sign in to. + example: org_01H945H0YD4F97JN9MATX7BYAG + authkit_authorization_code: + type: string + description: >- + An authorization code that can be exchanged for tokens by a + different application. + example: authkit_authz_code_abc123 + access_token: + type: string + description: A JWT containing information about the current session. + example: eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0 + refresh_token: + type: string + description: >- + [Exchange this + token](/reference/authkit/authentication/refresh-token) for a new + access token. + example: yAjhKk123NLIjdrBdGZPf8pLIDvK + authentication_method: + type: string + enum: + - SSO + - Password + - Passkey + - AppleOAuth + - BitbucketOAuth + - CrossAppAuth + - DiscordOAuth + - ExternalAuth + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - IntuitOAuth + - LinkedInOAuth + - MicrosoftOAuth + - SalesforceOAuth + - SlackOAuth + - VercelMarketplaceOAuth + - VercelOAuth + - XeroOAuth + - MagicAuth + - Impersonation + - MigratedSession + description: The authentication method used to initiate the session. + example: SSO + impersonator: + type: object + properties: + email: + type: string + description: >- + The email address of the WorkOS Dashboard user who is + impersonating the user. + example: admin@foocorp.com + reason: + type: + - string + - 'null' + description: >- + The justification the impersonator gave for impersonating the + user. + example: Investigating an issue with the customer's account. + required: + - email + - reason + description: >- + Information about the impersonator if this session was created via + impersonation. + oauth_tokens: + type: object + properties: + provider: + type: string + description: The OAuth provider used for authentication. + example: GoogleOAuth + refresh_token: + type: string + description: The refresh token from the OAuth provider. + example: 1//04g... + access_token: + type: string + description: The access token from the OAuth provider. + example: ya29.a0ARrdaM... + expires_at: + type: integer + description: The timestamp at which the access token expires. + example: 1735141800 + scopes: + type: array + items: + type: string + description: A list of OAuth scopes for which the access token is authorized. + example: + - profile + - email + - openid + required: + - provider + - refresh_token + - access_token + - expires_at + - scopes + description: The OAuth tokens from the identity provider, if applicable. + required: + - user + - access_token + - refresh_token + DeviceAuthorizationResponse: + type: object + properties: + device_code: + type: string + description: The device verification code. + example: CVE2wOfIFK4vhmiDBntpX9s8KT2f0qngpWYL0LGy9HxYgBRXUKIUkZB9BgIFho5h + user_code: + type: string + description: The end-user verification code. + example: BCDF-GHJK + verification_uri: + type: string + format: uri + description: The end-user verification URI. + example: https://authkit_domain/device + verification_uri_complete: + type: string + format: uri + description: Verification URI that includes the user code. + example: https://authkit_domain/device?user_code=BCDF-GHJK + expires_in: + type: number + description: Lifetime in seconds of the codes. + example: 300 + interval: + type: number + description: Minimum polling interval in seconds. + example: 5 + required: + - device_code + - user_code + - verification_uri + - expires_in + WebhookEndpointJson: + type: object + properties: + object: + type: string + description: Distinguishes the Webhook Endpoint object. + const: webhook_endpoint + id: + type: string + description: Unique identifier of the Webhook Endpoint. + example: we_0123456789 + endpoint_url: + type: string + description: The URL to which webhooks are sent. + example: https://example.com/webhooks + secret: + type: string + description: The secret used to sign webhook payloads. + example: whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4 + status: + type: string + enum: + - enabled + - disabled + description: Whether the Webhook Endpoint is enabled or disabled. + example: enabled + events: + type: array + items: + type: string + description: The events that the Webhook Endpoint is subscribed to. + example: + - user.created + - dsync.user.created + 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 + - endpoint_url + - secret + - status + - events + - created_at + - updated_at + WebhookEndpointList: + type: object + properties: + object: + type: string + description: Indicates this is a list response. + const: list + data: + type: array + items: + $ref: '#/components/schemas/WebhookEndpointJson' + 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: we_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: we_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: Pagination cursors for navigating between pages of results. + required: + - object + - data + - list_metadata + WidgetSessionTokenResponse: + type: object + properties: + token: + type: string + description: The widget session token. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNlc3Npb24... + required: + - token + SsoAuthorizeUrlResponse: + type: object + properties: + url: + type: string + format: uri + description: An OAuth 2.0 authorization URL. + example: >- + https://accounts.google.com/o/oauth2/v2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapi.workos.com%2Fsso%2Fcallback&response_type=code&scope=openid%20profile%20email + required: + - url + Profile: + type: object + properties: + object: + type: string + description: Distinguishes the profile object. + example: profile + const: profile + id: + type: string + description: Unique identifier of the profile. + example: prof_01DMC79VCBZ0NY2099737PSVF1 + organization_id: + type: + - string + - 'null' + description: The ID of the organization the user belongs to. + example: org_01EHQMYV6MBK39QC5PZXHY59C3 + connection_id: + type: string + description: The ID of the SSO connection used for authentication. + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + connection_type: + type: string + enum: + - Pending + - ADFSSAML + - AdpOidc + - AppleOAuth + - Auth0Migration + - Auth0SAML + - AzureSAML + - BitbucketOAuth + - CasSAML + - ClassLinkSAML + - CleverOIDC + - CloudflareSAML + - CyberArkSAML + - DiscordOAuth + - DuoSAML + - EntraIdOIDC + - GenericOIDC + - GenericSAML + - GitHubOAuth + - GitLabOAuth + - GoogleOAuth + - GoogleOIDC + - GoogleSAML + - IntuitOAuth + - JumpCloudSAML + - KeycloakSAML + - LastPassSAML + - LinkedInOAuth + - LoginGovOidc + - MagicLink + - MicrosoftOAuth + - MiniOrangeSAML + - NetIqSAML + - OktaOIDC + - OktaSAML + - OneLoginSAML + - OracleSAML + - PingFederateSAML + - PingOneSAML + - RipplingSAML + - SalesforceSAML + - ShibbolethGenericSAML + - ShibbolethSAML + - SimpleSamlPhpSAML + - SalesforceOAuth + - SlackOAuth + - TestIdp + - VercelMarketplaceOAuth + - VercelOAuth + - VMwareSAML + - XeroOAuth + description: The type of SSO connection. + example: GoogleOAuth + idp_id: + type: string + description: The user's unique identifier from the identity provider. + example: '103456789012345678901' + email: + type: string + description: The user's email address. + example: todd@example.com + first_name: + type: + - string + - 'null' + description: The user's first name. + example: Todd + last_name: + type: + - string + - 'null' + description: The user's last name. + example: Rundgren + name: + type: + - string + - 'null' + description: The user's full name. + example: Todd Rundgren + role: + description: >- + The role assigned to the user within the organization, if + applicable. + oneOf: + - $ref: '#/components/schemas/SlimRole' + - type: 'null' + roles: + description: >- + The roles assigned to the user within the organization, if + applicable. + oneOf: + - type: array + items: + $ref: '#/components/schemas/SlimRole' + - type: 'null' + groups: + type: array + items: + type: string + description: >- + The groups the user belongs to, as returned by the identity + provider. + example: + - Engineering + - Admins + custom_attributes: + type: object + additionalProperties: {} + description: >- + Custom attribute mappings defined for the connection, returned as + key-value pairs. + raw_attributes: + type: object + additionalProperties: {} + description: >- + The complete set of raw attributes returned by the identity + provider. + required: + - object + - id + - organization_id + - connection_id + - connection_type + - idp_id + - email + - first_name + - last_name + - name + - raw_attributes + SsoTokenResponse: + type: object + properties: + token_type: + type: string + description: The type of token issued. + const: Bearer + access_token: + type: string + description: >- + An access token that can be exchanged for a user profile. Access + tokens are short-lived — see the `expires_in` field for the exact + lifetime. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNzby... + expires_in: + type: integer + description: The lifetime of the access token in seconds. + example: 600 + profile: + $ref: '#/components/schemas/Profile' + description: The user profile returned by the identity provider. + oauth_tokens: + type: object + properties: + provider: + type: string + description: The OAuth provider used for authentication. + example: GoogleOAuth + refresh_token: + type: string + description: The refresh token from the OAuth provider. + example: 1//04g... + access_token: + type: string + description: The access token from the OAuth provider. + example: ya29.a0ARrdaM... + expires_at: + type: integer + description: The timestamp at which the access token expires. + example: 1735141800 + scopes: + type: array + items: + type: string + description: A list of OAuth scopes for which the access token is authorized. + example: + - profile + - email + - openid + required: + - provider + - refresh_token + - access_token + - expires_at + - scopes + description: OAuth tokens issued by the identity provider, if available. + required: + - token_type + - access_token + - expires_in + - profile + SsoLogoutAuthorizeResponse: + type: object + properties: + logout_url: + type: string + description: >- + The URL to redirect the user to in order to log out ([Logout + Redirect](/reference/sso/logout) endpoint ready to use). + example: https://auth.workos.com/sso/logout?token=eyJhbGciOiJSUzI1NiJ9 + logout_token: + type: string + description: >- + The logout token to be used in the [Logout + Redirect](/reference/sso/logout) endpoint. + example: >- + eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 + required: + - logout_url + - logout_token + JwksResponse: + type: object + properties: + keys: + type: array + items: + type: object + properties: + alg: + type: string + description: Algorithm. + const: RS256 + kty: + type: string + description: Key type. + const: RSA + use: + type: string + description: Key use (signature). + const: sig + x5c: + type: array + items: + type: string + description: X.509 certificate chain. + example: + - MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBCwUA... + 'n': + type: string + description: RSA modulus. + example: 0vx7agoebGc...eKnNs + e: + type: string + description: RSA exponent. + example: AQAB + kid: + type: string + description: Key ID. + example: key_01HXYZ123456789ABCDEFGHIJ + x5t#S256: + type: string + description: X.509 certificate SHA-256 thumbprint. + example: ZjQzYjI0OT...NmNjU0 + required: + - alg + - kty + - use + - x5c + - 'n' + - e + - kid + - x5t#S256 + description: The public keys used for verifying access tokens. + required: + - keys +security: + - bearer: [] diff --git a/src/utils/help-json.ts b/src/utils/help-json.ts index c8ef279..1a8f38b 100644 --- a/src/utils/help-json.ts +++ b/src/utils/help-json.ts @@ -293,6 +293,71 @@ const commands: CommandSchema[] = [ }, ], }, + { + name: 'api', + description: 'Make authenticated requests to the WorkOS API', + positionals: [ + { + name: 'endpoint', + type: 'string', + description: "API endpoint path (e.g. /users), or 'ls' to list endpoints", + required: false, + }, + { name: 'filter', type: 'string', description: 'Filter keyword (used with ls)', required: false }, + ], + options: [ + { + name: 'method', + type: 'string', + description: 'HTTP method (default: GET, or POST if body provided)', + required: false, + alias: 'X', + hidden: false, + }, + { name: 'data', type: 'string', description: 'JSON request body', required: false, alias: 'd', hidden: false }, + { + name: 'file', + type: 'string', + description: 'Read request body from a file (or - for stdin)', + required: false, + hidden: false, + }, + { + name: 'include', + type: 'boolean', + description: 'Show response headers', + required: false, + default: false, + alias: 'i', + hidden: false, + }, + apiKeyOpt, + { + name: 'dry-run', + type: 'boolean', + description: 'Show the request without executing it', + required: false, + default: false, + hidden: false, + }, + { + name: 'yes', + type: 'boolean', + description: 'Skip confirmation for mutating requests', + required: false, + default: false, + alias: 'y', + hidden: false, + }, + ], + examples: [ + 'workos api ls', + 'workos api ls users', + 'workos api /user_management/users', + 'workos api /organizations -d \'{"name":"Acme"}\'', + 'workos api /organizations/org_123 -X DELETE', + ], + }, { name: 'organization', description: 'Manage WorkOS organizations (create, update, get, list, delete)', From ca3c9af00cc7772dcc8f473378638c7ce9e34a79 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Mon, 4 May 2026 16:06:44 -0700 Subject: [PATCH 02/17] feat(api): add interactive request builder and fix duplicate resolveApiKey MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `workos api` with no args launches an interactive builder (TTY only): category picker → endpoint picker → path params → query params → body → confirm → execute - Non-TTY fallback prints usage instructions - Export colorMethod from index.ts to share with interactive.ts - Remove duplicate resolveApiKey resolution in runApiRequest (request.ts handles the fallback) --- src/bin.ts | 9 +- src/commands/api/index.ts | 34 +++++-- src/commands/api/interactive.ts | 164 ++++++++++++++++++++++++++++++++ 3 files changed, 198 insertions(+), 9 deletions(-) create mode 100644 src/commands/api/interactive.ts diff --git a/src/bin.ts b/src/bin.ts index e860c8e..e0b92eb 100644 --- a/src/bin.ts +++ b/src/bin.ts @@ -488,9 +488,14 @@ yargs(rawArgs) const endpoint = argv.endpoint as string | undefined; const filter = argv.filter as string | undefined; - const { runApiLs, runApiRequest } = await import('./commands/api/index.js'); + const { runApiLs, runApiRequest, runApiInteractive } = await import('./commands/api/index.js'); - if (!endpoint || endpoint === 'ls') { + if (!endpoint) { + await runApiInteractive(); + return; + } + + if (endpoint === 'ls') { runApiLs(filter); return; } diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index e399522..928864a 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -2,15 +2,16 @@ * `workos api` — generic authenticated API gateway. * * Modes: - * workos api ls [filter] — list endpoints from the embedded OpenAPI spec - * workos api [opts] — make an authenticated request + * workos api — interactive request builder (TTY only) + * workos api ls [filter] — list endpoints from the embedded OpenAPI spec + * workos api [opts] — make an authenticated request */ import chalk from 'chalk'; import { readFileSync } from 'node:fs'; import { loadCatalog, endpointsByTag } from './catalog.js'; import { apiRequest } from './request.js'; -import { resolveApiKey, resolveApiBaseUrl } from '../../lib/api-key.js'; +import { resolveApiBaseUrl } from '../../lib/api-key.js'; import { isJsonMode, outputJson } from '../../utils/output.js'; import { isNonInteractiveEnvironment } from '../../utils/environment.js'; @@ -26,6 +27,26 @@ export interface ApiCommandOptions { const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']); +// ── interactive ─────────────────────────────────────────────────────── + +export async function runApiInteractive(): Promise { + if (isNonInteractiveEnvironment()) { + console.log( + 'Interactive mode requires a TTY.\n\n' + + 'Usage:\n' + + ' workos api Make an API request\n' + + ' workos api ls [filter] List available endpoints\n' + + '\nExample:\n' + + ' workos api /user_management/users\n' + + ' workos api ls users', + ); + return; + } + + const { apiInteractive } = await import('./interactive.js'); + await apiInteractive(); +} + // ── ls ───────────────────────────────────────────────────────────────── export function runApiLs(filter?: string): void { @@ -69,7 +90,7 @@ export function runApiLs(filter?: string): void { for (const [tag, eps] of grouped) { console.log(`\n${chalk.bold(tag)}`); for (const ep of eps) { - const method = colorMethod(ep.method).padEnd(18); // padEnd accounts for ANSI codes + const method = colorMethod(ep.method).padEnd(18); console.log(` ${method} ${ep.path} ${chalk.dim(ep.summary)}`); } } @@ -81,7 +102,6 @@ export function runApiLs(filter?: string): void { export async function runApiRequest(endpoint: string, options: ApiCommandOptions): Promise { const body = await resolveBody(options); const method = (options.method ?? (body ? 'POST' : 'GET')).toUpperCase(); - const apiKey = options.apiKey ?? resolveApiKey(); const baseUrl = resolveApiBaseUrl(); if (options.dryRun) { @@ -112,7 +132,7 @@ export async function runApiRequest(endpoint: string, options: ApiCommandOptions const response = await apiRequest({ method, path: normalizePath(endpoint), - apiKey, + apiKey: options.apiKey, body: body ?? undefined, baseUrl, }); @@ -172,7 +192,7 @@ function printHeaders(status: number, headers: Headers): void { console.log(); } -function colorMethod(method: string): string { +export function colorMethod(method: string): string { switch (method) { case 'GET': return chalk.green(method); diff --git a/src/commands/api/interactive.ts b/src/commands/api/interactive.ts new file mode 100644 index 0000000..a6180bf --- /dev/null +++ b/src/commands/api/interactive.ts @@ -0,0 +1,164 @@ +/** + * Interactive API request builder for `workos api` (no args, TTY only). + * + * Flow: category → endpoint → path params → body → confirm → execute. + */ + +import chalk from 'chalk'; +import clack from '../../utils/clack.js'; +import { loadCatalog, endpointsByTag, type EndpointInfo } from './catalog.js'; +import { apiRequest } from './request.js'; +import { colorMethod } from './index.js'; +import { resolveApiKey, resolveApiBaseUrl } from '../../lib/api-key.js'; +import { isJsonMode, outputJson } from '../../utils/output.js'; + +export async function apiInteractive(): Promise { + const catalog = loadCatalog(); + const grouped = endpointsByTag(catalog); + + // 1. Select category + const tag = await clack.select({ + message: 'Select a category:', + options: catalog.tags.map((t) => { + const count = grouped.get(t)?.length ?? 0; + return { value: t, label: `${t} (${count})` }; + }), + }); + + if (clack.isCancel(tag)) process.exit(0); + + // 2. Select endpoint + const endpoints = grouped.get(tag as string)!; + const endpoint = await clack.select({ + message: 'Select an endpoint:', + options: endpoints.map((e) => ({ + value: e, + label: `${colorMethod(e.method).padEnd(18)} ${e.path}`, + hint: e.summary, + })), + }); + + if (clack.isCancel(endpoint)) process.exit(0); + + const ep = endpoint as EndpointInfo; + + // 3. Fill path parameters + let resolvedPath = ep.path; + for (const param of ep.pathParams) { + const hint = param.description || undefined; + const value = await clack.text({ + message: `${param.name}:`, + placeholder: hint, + validate: (v) => { + if (!v?.trim()) return `${param.name} is required`; + }, + }); + + if (clack.isCancel(value)) process.exit(0); + resolvedPath = resolvedPath.replace(`{${param.name}}`, (value as string).trim()); + } + + // 4. Query parameters (optional) + let queryString = ''; + if (ep.queryParams.length > 0) { + const wantsQuery = await clack.confirm({ + message: `Add query parameters? (${ep.queryParams.length} available)`, + initialValue: false, + }); + + if (clack.isCancel(wantsQuery)) process.exit(0); + + if (wantsQuery) { + const params: string[] = []; + for (const qp of ep.queryParams) { + const label = qp.required ? `${qp.name} (required):` : `${qp.name}:`; + const value = await clack.text({ + message: label, + placeholder: qp.description || undefined, + validate: qp.required + ? (v) => { + if (!v?.trim()) return `${qp.name} is required`; + } + : undefined, + }); + + if (clack.isCancel(value)) process.exit(0); + const trimmed = (value as string).trim(); + if (trimmed) { + params.push(`${encodeURIComponent(qp.name)}=${encodeURIComponent(trimmed)}`); + } + } + if (params.length > 0) { + queryString = `?${params.join('&')}`; + } + } + } + + // 5. Request body + let body: string | undefined; + if (ep.hasRequestBody) { + const wantsBody = await clack.confirm({ + message: 'Provide a request body?', + initialValue: ep.method === 'POST' || ep.method === 'PUT', + }); + + if (clack.isCancel(wantsBody)) process.exit(0); + + if (wantsBody) { + const bodyText = await clack.text({ + message: 'Request body (JSON):', + placeholder: '{"key": "value"}', + validate: (v) => { + if (!v?.trim()) return 'Body cannot be empty'; + try { + JSON.parse(v); + } catch { + return 'Invalid JSON'; + } + }, + }); + + if (clack.isCancel(bodyText)) process.exit(0); + body = (bodyText as string).trim(); + } + } + + const fullPath = `${resolvedPath}${queryString}`; + + // 6. Confirm + console.log(); + console.log(` ${colorMethod(ep.method)} ${fullPath}`); + if (body) { + console.log(chalk.dim(JSON.stringify(JSON.parse(body), null, 2))); + } + console.log(); + + const ok = await clack.confirm({ message: 'Execute this request?' }); + if (clack.isCancel(ok) || !ok) process.exit(0); + + // 7. Execute + const apiKey = resolveApiKey(); + const baseUrl = resolveApiBaseUrl(); + + const response = await apiRequest({ + method: ep.method, + path: fullPath, + apiKey, + baseUrl, + body, + }); + + console.log(chalk.dim(`\nHTTP ${response.status}`)); + + if (isJsonMode()) { + outputJson(response.body); + } else if (typeof response.body === 'object' && response.body !== null) { + console.log(JSON.stringify(response.body, null, 2)); + } else { + console.log(response.rawBody); + } + + if (response.status >= 400) { + process.exit(1); + } +} From 619b578fe906ab5022f91a4f8f6053d8d4d85bfc Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Mon, 4 May 2026 16:07:26 -0700 Subject: [PATCH 03/17] fix: Temporarily copy over the YAML spec --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 3679490..6e23e7e 100644 --- a/package.json +++ b/package.json @@ -93,7 +93,7 @@ "prebuild": "pnpm clean", "build:watch": "pnpm tsc -w", "build": "pnpm tsc", - "postbuild": "chmod +x ./dist/bin.js && cp -r scripts/** dist", + "postbuild": "chmod +x ./dist/bin.js && cp -r scripts/** dist && cp src/commands/api/workos-openapi-spec.yaml dist/commands/api/", "lint": "oxlint", "format": "oxfmt .", "format:check": "oxfmt --check .", From 0054db952171d02521508c4ba5a76742394834c9 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Mon, 4 May 2026 17:24:22 -0700 Subject: [PATCH 04/17] refactor(api): use @workos/openapi-spec package instead of vendored YAML Replace the 31K-line vendored OpenAPI spec with the published @workos/openapi-spec package. The catalog now resolves the spec via createRequire + require.resolve, keeping the same parse logic. --- package.json | 5 +- pnpm-lock.yaml | 8 + src/commands/api/catalog.ts | 7 +- src/commands/api/workos-openapi-spec.yaml | 31661 -------------------- 4 files changed, 14 insertions(+), 31667 deletions(-) delete mode 100644 src/commands/api/workos-openapi-spec.yaml diff --git a/package.json b/package.json index 6e23e7e..f20c66e 100644 --- a/package.json +++ b/package.json @@ -49,20 +49,21 @@ "@anthropic-ai/sdk": "^0.78.0", "@clack/core": "^1.0.1", "@clack/prompts": "1.0.1", + "@hono/node-server": "^1", "@napi-rs/keyring": "^1.2.0", "@workos-inc/node": "^8.7.0", + "@workos/openapi-spec": "^0.1.0", "@workos/skills": "0.5.0", "chalk": "^5.6.2", "diff": "^8.0.3", "fast-glob": "^3.3.3", + "hono": "^4", "ink": "^6.8.0", "opn": "^5.4.0", "react": "^19.2.4", "semver": "^7.7.4", "uuid": "^13.0.0", "xstate": "^5.28.0", - "hono": "^4", - "@hono/node-server": "^1", "yaml": "^2.8.2", "yargs": "^18.0.0", "zod": "^4.3.6" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ec9d8f9..ad4ec44 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -29,6 +29,9 @@ importers: '@workos-inc/node': specifier: ^8.7.0 version: 8.7.0 + '@workos/openapi-spec': + specifier: ^0.1.0 + version: 0.1.0 '@workos/skills': specifier: 0.5.0 version: 0.5.0 @@ -1071,6 +1074,9 @@ packages: resolution: {integrity: sha512-43HfXSR2Ez7M4ixpebuYVZzZf3gauh5jvv9lYnePg/x0XZMN2hjpEV3FD1LQX1vfMbqQ5gON3DN+/gH2rITm3A==} engines: {node: '>=20.15.0'} + '@workos/openapi-spec@0.1.0': + resolution: {integrity: sha512-pVw8SPFsva6UR8Z2ovE1DC4Aq1fRdPXywT8JP7yN1G8Y02+/kDb6KgFXmpKiv76XinUXDOAmU9tr/G73UI8mHw==} + '@workos/skills@0.5.0': resolution: {integrity: sha512-fScc+usjjvpyIOqSDq3AVmRpgpB5+yhyNfiqlSI/NsENe9C7Ynmbzx+XYwMJzGXpKIdUQQBHbvYRMOA1L+mWyw==} @@ -2515,6 +2521,8 @@ snapshots: iron-webcrypto: 2.0.0 jose: 6.1.3 + '@workos/openapi-spec@0.1.0': {} + '@workos/skills@0.5.0': dependencies: yaml: 2.8.3 diff --git a/src/commands/api/catalog.ts b/src/commands/api/catalog.ts index 941c5da..338cad0 100644 --- a/src/commands/api/catalog.ts +++ b/src/commands/api/catalog.ts @@ -3,9 +3,8 @@ */ import { parse as parseYaml } from 'yaml'; +import { createRequire } from 'node:module'; import { readFileSync } from 'node:fs'; -import { fileURLToPath } from 'node:url'; -import { dirname, join } from 'node:path'; export interface PathParam { name: string; @@ -83,8 +82,8 @@ let cachedCatalog: Catalog | undefined; export function loadCatalog(): Catalog { if (cachedCatalog) return cachedCatalog; - const specDir = dirname(fileURLToPath(import.meta.url)); - const specPath = join(specDir, 'workos-openapi-spec.yaml'); + const require = createRequire(import.meta.url); + const specPath = require.resolve('@workos/openapi-spec/spec'); const yamlText = readFileSync(specPath, 'utf-8'); cachedCatalog = parseSpec(yamlText); return cachedCatalog; diff --git a/src/commands/api/workos-openapi-spec.yaml b/src/commands/api/workos-openapi-spec.yaml deleted file mode 100644 index d30c2e8..0000000 --- a/src/commands/api/workos-openapi-spec.yaml +++ /dev/null @@ -1,31661 +0,0 @@ -openapi: 3.1.1 -paths: - /api_keys/validations: - post: - operationId: ApiKeysController_validateApiKey - summary: Validate API key - description: Validate an API key value and return the API key object if valid. - 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 - tags: - - api_keys - /api_keys/{id}: - delete: - operationId: ApiKeysController_delete - summary: Delete an API key - description: >- - Permanently deletes an API key. This action cannot be undone. Once - deleted, any requests using this API key will fail authentication. - 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 - tags: - - api_keys - /audit_logs/actions: - get: - operationId: AuditLogValidatorsController_list - summary: List Actions - description: Get a list of all Audit Log actions in the current environment. - 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. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - allOf: - - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - 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: ala_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: ala_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - - type: object - properties: - data: - type: array - description: The list of records for the current page. - items: - $ref: '#/components/schemas/AuditLogActionJson' - '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 - tags: - - audit-logs - /audit_logs/actions/{actionName}/schemas: - post: - operationId: AuditLogValidatorVersionsController_create - summary: Create Schema - description: >- - Creates a new Audit Log schema used to validate the payload of incoming - Audit Log Events. If the `action` does not exist, it will also be - created. - parameters: - - name: actionName - required: true - in: path - description: The name of the Audit Log action. - schema: - example: user.logged_in - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogSchemaDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogSchemaJson' - '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 - tags: - - audit-logs - get: - operationId: AuditLogValidatorVersionsController_schemas - summary: List Schemas - description: >- - Get a list of all schemas for the Audit Logs action identified by - `:name`. - parameters: - - name: actionName - required: true - in: path - description: The name of the Audit Log action. - schema: - example: user.logged_in - type: string - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - allOf: - - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - 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: als_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: als_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - - type: object - properties: - data: - type: array - description: The list of records for the current page. - items: - $ref: '#/components/schemas/AuditLogSchemaJson' - '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 - tags: - - audit-logs - /audit_logs/events: - post: - operationId: AuditLogEventsController_create - summary: Create Event - description: >- - Create an Audit Log Event. - - - This API supports idempotency which guarantees that performing the same - operation multiple times will have the same result as if the operation - were performed only once. This is handy in situations where you may need - to retry a request due to a failure or prevent accidental duplicate - requests from creating more than one resource. - - - To achieve idempotency, you can add `Idempotency-Key` request header to - a Create Event request with a unique string as the value. Each - subsequent request matching this unique string will return the same - response. We suggest using [v4 - UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) for - idempotency keys to avoid collisions. - - - Idempotency keys expire after 24 hours. The API will generate a new - response if you submit a request with an expired key. - parameters: - - name: idempotency-key - in: header - description: >- - A unique string to prevent duplicate requests. Each subsequent - request matching this unique string will return the same response. - We suggest using v4 UUIDs. Keys expire after 24 hours. - required: false - schema: - type: string - example: 884793cd-bef4-46cf-8790-e3d4957a09ce - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogEventIngestionDto' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogEventCreateResponse' - example: - success: true - description: OK - '400': - content: - application/json: - schema: - anyOf: - - type: object - properties: - errors: - type: array - items: - type: object - properties: - instancePath: - type: string - description: >- - The JSON path to the invalid field in the event - payload. - example: /targets - required: - - instancePath - description: The list of validation errors. - message: - type: string - description: A human-readable description of the error. - example: Invalid Audit Log event. - code: - type: string - description: The error code identifying the type of error. - example: invalid_audit_log_event - required: - - errors - - message - - code - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Organization not found: - 'org_01EHQMYV6MBK39QC5PZXHY59C3'. - required: - - message - example: - message: Invalid Audit Log event. - code: invalid_audit_log_event - errors: - - instancePath: /targets - description: Bad Request - '404': - 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 - example: - message: "Organization not found: 'org_01EHQMYV6MBK39QC5PZXHY59C3'." - description: Not Found - '422': - content: - application/json: - schema: - type: object - properties: - 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. - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - errors - - message - example: - message: Validation failed. - errors: - - code: required - field: event.action - description: Unprocessable Entity - '429': - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Too many requests. - code: - type: string - description: The error code identifying the type of error. - example: rate_limit_exceeded - required: - - message - - code - example: - message: Too many requests. - code: rate_limit_exceeded - description: '' - tags: - - audit-logs - /audit_logs/exports: - post: - operationId: AuditLogExportsController_exports - summary: Create Export - description: >- - Create an Audit Log Export. Exports are scoped to a single organization - within a specified date range. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogExportCreationDto' - responses: - '201': - description: The created Audit Log Export object. - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogExportJson' - example: - object: audit_log_export - id: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V - state: pending - created_at: '2022-09-02T17:14:57.094Z' - updated_at: '2022-09-02T17:14:57.094Z' - '400': - description: Invalid request parameters or date range. - content: - application/json: - schema: - anyOf: - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Organization not found: - 'org_01EHQMYV6MBK39QC5PZXHY59C3'. - required: - - message - - type: object - properties: - message: - type: array - items: - type: string - description: >- - A list of human-readable error messages describing the - validation failures. - example: - - Invalid date range - error: - type: string - description: The error type. - example: Bad Request - required: - - message - - error - example: - message: Invalid date range - code: invalid_audit_log_export_range_date - tags: - - audit-logs - /audit_logs/exports/{auditLogExportId}: - get: - operationId: AuditLogExportsController_export - summary: Get Export - description: >- - Get an Audit Log Export. The URL will expire after 10 minutes. If the - export is needed again at a later time, refetching the export will - regenerate the URL. - parameters: - - name: auditLogExportId - required: true - in: path - description: The unique ID of the Audit Log Export. - schema: - type: string - example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V - responses: - '200': - description: The Audit Log Export object. - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogExportJson' - example: - 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' - '404': - description: Audit Log Export 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 - example: - message: >- - Audit Log Export not found: - 'audit_log_export_01GBZK5MP7TD1YCFQHFR22180V'. - tags: - - audit-logs - /auth/challenges/{id}/verify: - post: - operationId: AuthenticationChallengesController_verify - summary: Verify Challenge - description: Verifies an Authentication Challenge. - parameters: - - name: id - required: true - in: path - description: The unique ID of the Authentication Challenge. - schema: - type: string - example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The one-time code to verify. - example: '123456' - required: - - code - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/AuthenticationChallengeVerifyResponse' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: one_time_code_too_many_attempts - const: one_time_code_too_many_attempts - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - multi-factor-auth.challenges - /auth/factors/enroll: - post: - operationId: AuthenticationFactorsController_create - summary: Enroll Factor - description: >- - Enrolls an Authentication Factor to be used as an additional factor of - authentication. The returned ID should be used to create an - authentication Challenge. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - type: - type: string - enum: - - generic_otp - - sms - - totp - description: The type of factor to enroll. - example: totp - phone_number: - type: string - description: Required when type is 'sms'. - example: '+15555555555' - totp_issuer: - type: string - description: Required when type is 'totp'. - example: Foo Corp - totp_user: - type: string - description: Required when type is 'totp'. - example: alan.turing@example.com - user_id: - type: string - description: The ID of the user to associate the factor with. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - required: - - type - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/AuthenticationFactorEnrolled' - '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 - tags: - - multi-factor-auth - /auth/factors/{id}: - get: - operationId: AuthenticationFactorsController_get - summary: Get Factor - description: Gets an Authentication Factor. - parameters: - - name: id - required: true - in: path - description: The unique ID of the Factor. - schema: - type: string - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/AuthenticationFactor' - example: - 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' - description: OK - '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 - tags: - - multi-factor-auth - delete: - operationId: AuthenticationFactorsController_delete - summary: Delete Factor - description: Permanently deletes an Authentication Factor. It cannot be undone. - parameters: - - name: id - required: true - in: path - description: The unique ID of the Factor. - schema: - type: string - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - responses: - '200': - description: OK - '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 - tags: - - multi-factor-auth - /auth/factors/{id}/challenge: - post: - operationId: AuthenticationFactorsController_challenge - summary: Challenge Factor - description: Creates a Challenge for an Authentication Factor. - parameters: - - name: id - required: true - in: path - description: The unique ID of the Authentication Factor to be challenged. - schema: - type: string - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/ChallengeAuthenticationFactorDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/AuthenticationChallenge' - '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 - tags: - - multi-factor-auth - /authkit/oauth2/complete: - post: - operationId: ExternalAuthController_completeLogin - summary: Complete external authentication - description: >- - Completes an external authentication flow and returns control to - AuthKit. This endpoint is used with [Standalone - Connect](/authkit/connect/standalone) to bridge your existing - authentication system with the Connect OAuth API infrastructure. - - - After successfully authenticating a user in your application, calling - this endpoint will: - - - - Create or update the user in AuthKit, using the given `id` as its - `external_id`. - - - Return a `redirect_uri` your application should redirect to in order - for AuthKit to complete the flow - - - Users are automatically created or updated based on the `id` and `email` - provided. If a user with the same `id` exists, their information is - updated. Otherwise, a new user is created. - - - If you provide a new `id` with an `email` that already belongs to an - existing user, the request will fail with an error as email addresses - are unique to a user. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UserManagementLoginRequest' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAuthCompleteResponse' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: external_auth_session_already_completed - const: external_auth_session_already_completed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_not_allowed - const: email_change_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_not_available - const: email_not_available - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_email - const: invalid_email - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - error: - type: string - description: The HTTP error type. - example: Bad Request - message: - type: string - description: A human-readable description of the error. - example: Claim "sub" is reserved and cannot be used. - required: - - error - - 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 - tags: - - workos-connect - /authorization/organization_memberships/{organization_membership_id}/check: - post: - operationId: AuthorizationController_check - summary: Check authorization - description: >- - Check if an organization membership has a specific permission on a - resource. Supports identification by resource_id OR by - resource_external_id + resource_type_slug. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership to check. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CheckAuthorizationDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationCheck' - '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 - tags: - - authorization - x-mutually-exclusive-body-groups: &ref_3 - resource_target: - optional: false - variants: - by_id: - - resource_id - by_external_id: - - resource_external_id - - resource_type_slug - /authorization/organization_memberships/{organization_membership_id}/resources: - get: - operationId: AuthorizationController_listResourcesForMembership - summary: List resources for organization membership - description: >- - Returns all child resources of a parent resource where the organization - membership has a specific permission. This is useful for resource - discovery—answering "What projects can this user access in this - workspace?" - - - You must provide either `parent_resource_id` or both - `parent_resource_external_id` and `parent_resource_type_slug` to - identify the parent resource. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: permission_slug - required: true - in: query - description: >- - The permission slug to filter by. Only child resources where the - organization membership has this permission are returned. - schema: - type: string - example: project:read - - name: parent_resource_id - required: false - in: query - description: >- - The WorkOS ID of the parent resource. Provide this or both - `parent_resource_external_id` and `parent_resource_type_slug`, but - not both. Mutually exclusive with `parent_resource_type_slug` and - `parent_resource_external_id`. - schema: - type: string - example: authz_resource_01XYZ789 - - name: parent_resource_type_slug - required: false - in: query - description: >- - The slug of the parent resource type. Must be provided together with - `parent_resource_external_id`. Required with - `parent_resource_external_id`. Mutually exclusive with - `parent_resource_id`. - schema: - type: string - example: project - - name: parent_resource_external_id - required: false - in: query - description: >- - The application-specific external identifier of the parent resource. - Must be provided together with `parent_resource_type_slug`. Required - with `parent_resource_type_slug`. Mutually exclusive with - `parent_resource_id`. - schema: - type: string - example: external_project_123 - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationResourceList' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - x-mutually-exclusive-parameter-groups: - parent_resource: - optional: false - variants: - by_id: - - parent_resource_id - by_external_id: - - parent_resource_type_slug - - parent_resource_external_id - /authorization/organization_memberships/{organization_membership_id}/resources/{resource_id}/permissions: - get: - operationId: AuthorizationController_listEffectivePermissions - summary: List effective permissions for an organization membership on a resource - description: >- - Returns all permissions the organization membership effectively has on a - resource, including permissions inherited through roles assigned to - ancestor resources. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPermissionList' - '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 - tags: - - authorization - /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions: - get: - operationId: AuthorizationController_listEffectivePermissionsByExternalId - summary: >- - List effective permissions for an organization membership on a resource - by external ID - description: >- - Returns all permissions the organization membership effectively has on a - resource identified by its external ID, including permissions inherited - through roles assigned to ancestor resources. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - name: resource_type_slug - required: true - in: path - description: The slug of the resource type. - schema: - type: string - example: document - - name: external_id - required: true - in: path - description: An identifier you provide to reference the resource in your system. - schema: - type: string - example: doc-456 - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPermissionList' - '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 - tags: - - authorization - /authorization/organization_memberships/{organization_membership_id}/role_assignments: - get: - operationId: AuthorizationRoleAssignmentsController_listRoleAssignments - summary: List role assignments - description: >- - List all role assignments for an organization membership. This returns - all roles that have been assigned to the user on resources, including - organization-level and sub-resource roles. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/RoleAssignmentList' - '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 - tags: - - authorization - post: - operationId: AuthorizationRoleAssignmentsController_assignRole - summary: Assign a role - description: Assign a role to an organization membership on a specific resource. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AssignRoleDto' - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/RoleAssignment' - example: - object: role_assignment - id: role_assignment_01HXYZ123456789ABCDEFGH - role: - slug: editor - resource: - id: authz_resource_01HXYZ123456789ABCDEFGH - external_id: project-ext-456 - resource_type_slug: project - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - description: Created - '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 - tags: - - authorization - x-mutually-exclusive-body-groups: &ref_4 - resource_target: - optional: false - variants: - by_id: - - resource_id - by_external_id: - - resource_external_id - - resource_type_slug - delete: - operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria - summary: Remove a role assignment - description: Remove a role assignment by role slug and resource. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/RemoveRoleDto' - responses: - '204': - description: Role assignment removed successfully. - '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 - tags: - - authorization - x-mutually-exclusive-body-groups: &ref_5 - resource_target: - optional: false - variants: - by_id: - - resource_id - by_external_id: - - resource_external_id - - resource_type_slug - /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}: - delete: - operationId: AuthorizationRoleAssignmentsController_removeRoleById - summary: Remove a role assignment by ID - description: Remove a role assignment using its ID. - parameters: - - name: organization_membership_id - required: true - in: path - description: The ID of the organization membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - name: role_assignment_id - required: true - in: path - description: The ID of the role assignment to remove. - schema: - type: string - example: role_assignment_01HXYZ123456789ABCDEFGH - responses: - '204': - description: Role assignment removed successfully. - '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 - tags: - - authorization - /authorization/organizations/{organizationId}/roles: - post: - operationId: AuthorizationOrganizationRolesController_create - summary: Create a custom role - description: Create a new custom role for this organization. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateOrganizationRoleDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: org-billing-admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Billing Administrator - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage billing and invoices - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: organization_role_slug_conflict - const: organization_role_slug_conflict - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - authorization - get: - operationId: AuthorizationOrganizationRolesController_list - summary: List custom roles - description: >- - Get a list of all roles that apply to an organization. This includes - both environment roles and custom roles, returned in priority order. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/RoleList' - '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 - tags: - - authorization - /authorization/organizations/{organizationId}/roles/{slug}: - get: - operationId: AuthorizationOrganizationRolesController_get - summary: Get a custom role - description: >- - Retrieve a role that applies to an organization by its slug. This can - return either an environment role or a custom role. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: slug - required: true - in: path - description: The slug of the role. - schema: - type: string - example: org-billing-admin - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: org-billing-admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Billing Manager - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can view and export billing reports - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '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 - tags: - - authorization - patch: - operationId: AuthorizationOrganizationRolesController_update - summary: Update a custom role - description: >- - Update an existing custom role. Only the fields provided in the request - body will be updated. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: slug - required: true - in: path - description: The slug of the role. - schema: - type: string - example: org-billing-admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateOrganizationRoleDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: org-billing-admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Finance Administrator - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all financial operations - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - delete: - operationId: AuthorizationOrganizationRolesController_delete - summary: Delete a custom role - description: Delete an existing custom role. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: slug - required: true - in: path - description: The slug of the role. - schema: - type: string - example: org-admin - responses: - '204': - description: No Content - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: role_has_assignments - const: role_has_assignments - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: role_has_group_role_mappings - const: role_has_group_role_mappings - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - authorization - /authorization/organizations/{organizationId}/roles/{slug}/permissions: - put: - operationId: AuthorizationOrganizationRolePermissionsController_setPermissions - summary: Set permissions for a custom role - description: Replace all permissions on a custom role with the provided list. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: slug - required: true - in: path - description: The slug of the role. - schema: - type: string - example: org-admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/SetRolePermissionsDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: org-admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Organization Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - example: - - billing:read - - billing:write - - invoices:manage - - reports:view - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '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 - tags: - - authorization - post: - operationId: AuthorizationOrganizationRolePermissionsController_addPermission - summary: Add a permission to a custom role - description: >- - Add a single permission to a custom role. If the permission is already - assigned to the role, this operation has no effect. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: slug - required: true - in: path - description: The slug of the role. - schema: - type: string - example: org-admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AddRolePermissionDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: org-admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Organization Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - example: - - reports:export - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}: - delete: - operationId: AuthorizationOrganizationRolePermissionsController_removePermission - summary: Remove a permission from a custom role - description: Remove a single permission from a custom role by its slug. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: slug - required: true - in: path - description: The slug of the role. - schema: - type: string - example: org-admin - - name: permissionSlug - required: true - in: path - description: The slug of the permission to remove. - schema: - type: string - example: documents:read - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Role' - '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 - tags: - - authorization - /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}: - get: - operationId: AuthorizationResourcesByExternalIdController_getByExternalId - summary: Get a resource by external ID - description: >- - Retrieve the details of an authorization resource by its external ID, - organization, and resource type. This is useful when you only have the - external ID from your system and need to fetch the full resource - details. - parameters: - - name: organization_id - required: true - in: path - description: The ID of the organization that owns the resource. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: resource_type_slug - required: true - in: path - description: The slug of the resource type. - schema: - type: string - example: project - - name: external_id - required: true - in: path - description: An identifier you provide to reference the resource in your system. - schema: - type: string - example: proj-456 - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationResource' - '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 - tags: - - authorization - patch: - operationId: AuthorizationResourcesByExternalIdController_updateByExternalId - summary: Update a resource by external ID - description: Update an existing authorization resource using its external ID. - parameters: - - name: organization_id - required: true - in: path - description: The ID of the organization that owns the resource. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: resource_type_slug - required: true - in: path - description: The slug of the resource type. - schema: - type: string - example: project - - name: external_id - required: true - in: path - description: An identifier you provide to reference the resource in your system. - schema: - type: string - example: proj-456 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAuthorizationResourceDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Updated Name - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Updated description - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in - your system. - example: proj-456 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: lock_timeout - const: lock_timeout - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_type_update_in_progress - const: resource_type_update_in_progress - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - authorization - x-mutually-exclusive-body-groups: &ref_0 - parent_resource: - optional: true - variants: - by_id: - - parent_resource_id - by_external_id: - - parent_resource_external_id - - parent_resource_type_slug - delete: - operationId: AuthorizationResourcesByExternalIdController_deleteByExternalId - summary: Delete an authorization resource by external ID - description: >- - Delete an authorization resource by organization, resource type, and - external ID. This also deletes all descendant resources. - parameters: - - name: organization_id - required: true - in: path - description: The ID of the organization that owns the resource. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: resource_type_slug - required: true - in: path - description: The slug of the resource type. - schema: - type: string - example: project - - name: external_id - required: true - in: path - description: An identifier you provide to reference the resource in your system. - schema: - type: string - example: proj-456 - - name: cascade_delete - required: false - in: query - description: >- - If true, deletes all descendant resources and role assignments. If - not set and the resource has children or assignments, the request - will fail. - schema: - type: boolean - default: false - example: false - responses: - '204': - description: No Content - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: lock_timeout - const: lock_timeout - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_has_dependents - const: resource_has_dependents - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_type_update_in_progress - const: resource_type_update_in_progress - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - authorization - /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships: - get: - operationId: >- - AuthorizationResourcesByExternalIdController_listOrganizationMembershipsForResourceByExternalId - summary: List memberships for a resource by external ID - description: >- - Returns all organization memberships that have a specific permission on - a resource, using the resource's external ID. This is useful for - answering "Who can access this resource?" when you only have the - external ID. - parameters: - - name: organization_id - required: true - in: path - description: The ID of the organization that owns the resource. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: resource_type_slug - required: true - in: path - description: The slug of the resource type this resource belongs to. - schema: - example: project - type: string - - name: external_id - required: true - in: path - description: An identifier you provide to reference the resource in your system. - schema: - example: proj-456 - type: string - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: permission_slug - required: true - in: query - description: >- - The permission slug to filter by. Only users with this permission on - the resource are returned. - schema: - type: string - example: project:read - - name: assignment - required: false - in: query - description: >- - Filter by assignment type. Use "direct" for direct assignments only, - or "indirect" to include inherited assignments. - schema: - type: string - enum: - - direct - - indirect - example: direct - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: >- - #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - /authorization/permissions: - get: - operationId: AuthorizationPermissionsController_list - summary: List permissions - description: Get a list of all permissions in your WorkOS environment. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPermissionList' - '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 - tags: - - permissions - post: - operationId: AuthorizationPermissionsController_create - summary: Create a permission - description: >- - Create a new permission in your WorkOS environment. The permission can - then be assigned to environment roles and custom roles. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAuthorizationPermissionDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Permission object. - const: permission - id: - type: string - description: Unique identifier of the Permission. - example: perm_01HXYZ123456789ABCDEFGHIJ - slug: - type: string - description: >- - A unique key to reference the permission. Must be - lowercase and contain only letters, numbers, hyphens, - underscores, colons, periods, and asterisks. - example: documents:read - name: - type: string - description: A descriptive name for the Permission. - example: View Documents - description: - type: - - string - - 'null' - description: An optional description of the Permission. - example: Allows viewing document contents - system: - type: boolean - description: >- - Whether the permission is a system permission. System - permissions are managed by WorkOS and cannot be deleted. - example: false - resource_type_slug: - type: string - description: >- - The slug of the resource type associated with the - permission. - example: document - 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 - - slug - - name - - description - - system - - resource_type_slug - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - '409': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: permission_slug_conflict - const: permission_slug_conflict - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - permissions - /authorization/permissions/{slug}: - get: - operationId: AuthorizationPermissionsController_find - summary: Get a permission - description: Retrieve a permission by its unique slug. - parameters: - - name: slug - required: true - in: path - description: >- - A unique key to reference the permission. Must be lowercase and - contain only letters, numbers, hyphens, underscores, colons, - periods, and asterisks. - schema: - example: documents:read - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPermission' - '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 - tags: - - permissions - patch: - operationId: AuthorizationPermissionsController_update - summary: Update a permission - description: >- - Update an existing permission. Only the fields provided in the request - body will be updated. - parameters: - - name: slug - required: true - in: path - description: >- - A unique key to reference the permission. Must be lowercase and - contain only letters, numbers, hyphens, underscores, colons, - periods, and asterisks. - schema: - example: documents:read - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAuthorizationPermissionDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationPermission' - '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 - tags: - - permissions - delete: - operationId: AuthorizationPermissionsController_delete - summary: Delete a permission - description: Delete an existing permission. System permissions cannot be deleted. - parameters: - - name: slug - required: true - in: path - description: >- - A unique key to reference the permission. Must be lowercase and - contain only letters, numbers, hyphens, underscores, colons, - periods, and asterisks. - schema: - example: documents:read - type: string - responses: - '204': - description: No Content - '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 - tags: - - permissions - /authorization/resources: - get: - operationId: AuthorizationResourcesController_list - summary: List resources - description: Get a paginated list of authorization resources. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization_id - required: false - in: query - description: Filter resources by organization ID. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - - name: resource_type_slug - required: false - in: query - description: Filter resources by resource type slug. - schema: - type: string - example: project - - name: resource_external_id - required: false - in: query - description: Filter resources by external ID. - schema: - type: string - example: my-project-123 - - name: parent_resource_id - required: false - in: query - description: >- - Filter resources by parent resource ID. Mutually exclusive with - `parent_resource_type_slug` and `parent_external_id`. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - - name: parent_resource_type_slug - required: false - in: query - description: >- - Filter resources by parent resource type slug. Required with - `parent_external_id`. Mutually exclusive with `parent_resource_id`. - schema: - type: string - example: workspace - - name: parent_external_id - required: false - in: query - description: >- - Filter resources by parent external ID. Required with - `parent_resource_type_slug`. Mutually exclusive with - `parent_resource_id`. - schema: - type: string - example: ext-workspace-123 - - name: search - required: false - in: query - description: Search resources by name. - schema: - type: string - example: Website Redesign - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationResourceList' - '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 - '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 - tags: - - authorization - x-mutually-exclusive-parameter-groups: - parent: - optional: true - variants: - by_id: - - parent_resource_id - by_external_id: - - parent_resource_type_slug - - parent_external_id - post: - operationId: AuthorizationResourcesController_create - summary: Create an authorization resource - description: Create a new authorization resource. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateAuthorizationResourceDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Acme Workspace - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Primary workspace for the Acme team - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - parent_resource_id: - type: - - string - - 'null' - description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in - your system. - example: my-workspace-01 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: workspace - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: lock_timeout - const: lock_timeout - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: authorization_resource_external_id_conflict - const: authorization_resource_external_id_conflict - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_type_update_in_progress - const: resource_type_update_in_progress - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - authorization - x-mutually-exclusive-body-groups: &ref_6 - parent_resource: - optional: true - variants: - by_id: - - parent_resource_id - by_external_id: - - parent_resource_external_id - - parent_resource_type_slug - /authorization/resources/{resource_id}: - get: - operationId: AuthorizationResourcesController_findById - summary: Get a resource - description: Retrieve the details of an authorization resource by its ID. - parameters: - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationResource' - '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 - tags: - - authorization - patch: - operationId: AuthorizationResourcesController_update - summary: Update a resource - description: Update an existing authorization resource. - parameters: - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAuthorizationResourceDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Updated Name - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Updated description - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in - your system. - example: proj-456 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: lock_timeout - const: lock_timeout - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_type_update_in_progress - const: resource_type_update_in_progress - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - authorization - x-mutually-exclusive-body-groups: *ref_0 - delete: - operationId: AuthorizationResourcesController_delete - summary: Delete an authorization resource - description: Delete an authorization resource and all its descendants. - parameters: - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - - name: cascade_delete - required: false - in: query - description: >- - If true, deletes all descendant resources and role assignments. If - not set and the resource has children or assignments, the request - will fail. - schema: - type: boolean - default: false - example: false - responses: - '204': - description: No Content - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: lock_timeout - const: lock_timeout - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_has_dependents - const: resource_has_dependents - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: resource_type_update_in_progress - const: resource_type_update_in_progress - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - authorization - /authorization/resources/{resource_id}/organization_memberships: - get: - operationId: AuthorizationResourcesController_listOrganizationMembershipsForResource - summary: List organization memberships for resource - description: >- - Returns all organization memberships that have a specific permission on - a resource instance. This is useful for answering "Who can access this - resource?". - parameters: - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: permission_slug - required: true - in: query - description: >- - The permission slug to filter by. Only users with this permission on - the resource are returned. - schema: - type: string - example: document:edit - - name: assignment - required: false - in: query - description: >- - Filter by assignment type. Use `direct` for direct assignments only, - or `indirect` to include inherited assignments. - schema: - type: string - enum: - - direct - - indirect - example: direct - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: >- - #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - /authorization/roles: - post: - operationId: AuthorizationRolesController_create - summary: Create an environment role - description: Create a new environment role. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateRoleDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: editor - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Editor - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can edit resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: role_slug_conflict - const: role_slug_conflict - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - authorization - get: - operationId: AuthorizationRolesController_list - summary: List environment roles - description: List all environment roles in priority order. - parameters: [] - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/RoleList' - '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 - tags: - - authorization - /authorization/roles/{slug}: - get: - operationId: AuthorizationRolesController_get - summary: Get an environment role - description: Get an environment role by its slug. - parameters: - - name: slug - required: true - in: path - description: The slug of the environment role. - schema: - type: string - example: admin - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Role' - '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 - tags: - - authorization - patch: - operationId: AuthorizationRolesController_update - summary: Update an environment role - description: Update an existing environment role. - parameters: - - name: slug - required: true - in: path - description: The slug of the environment role. - schema: - type: string - example: admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateRoleDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Super Administrator - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Full administrative access to all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - /authorization/roles/{slug}/permissions: - put: - operationId: AuthorizationRolePermissionsController_setPermissions - summary: Set permissions for an environment role - description: Replace all permissions on an environment role with the provided list. - parameters: - - name: slug - required: true - in: path - description: The slug of the environment role. - schema: - type: string - example: admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/SetRolePermissionsDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - example: - - billing:read - - billing:write - - invoices:manage - - reports:view - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - post: - operationId: AuthorizationRolePermissionsController_addPermission - summary: Add a permission to an environment role - description: >- - Add a single permission to an environment role. If the permission is - already assigned to the role, this operation has no effect. - parameters: - - name: slug - required: true - in: path - description: The slug of the environment role. - schema: - type: string - example: admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AddRolePermissionDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - example: - - reports:export - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - authorization - /connect/applications: - get: - operationId: ApplicationsController_list - summary: List Connect Applications - description: >- - List all Connect Applications in the current environment with optional - filtering. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization_id - required: false - in: query - description: Filter Connect Applications by organization ID. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ConnectApplicationList' - '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 - tags: - - applications - post: - operationId: ApplicationsController_create - summary: Create a Connect Application - description: >- - Create a new Connect Application. Supports both OAuth and - Machine-to-Machine (M2M) application types. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/CreateOAuthApplicationDto' - - $ref: '#/components/schemas/CreateM2MApplicationDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/ConnectApplication' - '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 - tags: - - applications - /connect/applications/{id}: - get: - operationId: ApplicationsController_find - summary: Get a Connect Application - description: Retrieve details for a specific Connect Application by ID or client ID. - parameters: - - name: id - required: true - in: path - description: The application ID or client ID of the Connect Application. - schema: - type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ConnectApplication' - '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 - tags: - - applications - put: - operationId: ApplicationsController_update - summary: Update a Connect Application - description: >- - Update an existing Connect Application. For OAuth applications, you can - update redirect URIs. For all applications, you can update the name, - description, and scopes. - parameters: - - name: id - required: true - in: path - description: The application ID or client ID of the Connect Application. - schema: - type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateOAuthApplicationDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ConnectApplication' - '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 - tags: - - applications - delete: - operationId: ApplicationsController_delete - summary: Delete a Connect Application - description: Delete an existing Connect Application. - parameters: - - name: id - required: true - in: path - description: The application ID or client ID of the Connect Application. - schema: - type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ - 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 - tags: - - applications - /connect/applications/{id}/client_secrets: - get: - operationId: ApplicationCredentialsController_list - summary: List Client Secrets for a Connect Application - description: List all client secrets associated with a Connect Application. - parameters: - - name: id - required: true - in: path - description: The application ID or client ID of the Connect Application. - schema: - type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ - responses: - '200': - description: OK - content: - application/json: - schema: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the connect application secret object. - const: connect_application_secret - id: - type: string - description: The unique ID of the client secret. - example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q - secret_hint: - type: string - description: >- - A hint showing the last few characters of the secret - value. - example: abc123 - last_used_at: - type: - - string - - 'null' - description: >- - The timestamp when the client secret was last used, or - null if never used. - example: null - 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 - - secret_hint - - last_used_at - - created_at - - updated_at - '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 - tags: - - application.client-secrets - post: - operationId: ApplicationCredentialsController_create - summary: Create a new client secret for a Connect Application - description: Create new secrets for a Connect Application. - parameters: - - name: id - required: true - in: path - description: The application ID or client ID of the Connect Application. - schema: - type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateApplicationSecretDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/NewConnectApplicationSecret' - '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 - tags: - - application.client-secrets - /connect/client_secrets/{id}: - delete: - operationId: ApplicationCredentialsController_delete - summary: Delete a Client Secret - description: Delete (revoke) an existing client secret. - parameters: - - name: id - required: true - in: path - description: The unique ID of the client secret. - schema: - type: string - example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q - 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 - tags: - - application.client-secrets - /connections: - get: - operationId: ConnectionsController_list - summary: List Connections - description: >- - Get a list of all of your existing connections matching the criteria - specified. - 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. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: connection_type - required: false - in: query - description: Filter Connections by their type. - schema: - example: GithubOAuth - enum: - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - CloudflareSAML - - ClassLinkSAML - - CleverOIDC - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GithubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - type: string - - name: domain - required: false - in: query - description: Filter Connections by their associated domain. - schema: - example: foo-corp.com - type: string - - name: organization_id - required: false - in: query - description: Filter Connections by their associated organization. - schema: - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - type: string - - name: search - required: false - in: query - description: Searchable text to match against Connection names. - schema: - example: Foo Corp - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ConnectionList' - '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 - '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 - tags: - - connections - /connections/{id}: - get: - operationId: ConnectionsController_find - summary: Get a Connection - description: Get the details of an existing connection. - parameters: - - name: id - required: true - in: path - description: Unique identifier for the Connection. - schema: - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Connection' - '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 - tags: - - connections - delete: - operationId: ConnectionsController_delete - summary: Delete a Connection - description: Permanently deletes an existing connection. It cannot be undone. - parameters: - - name: id - required: true - in: path - description: Unique identifier for the Connection. - schema: - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - '204': - description: No Content - '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 - tags: - - connections - /data-integrations/{slug}/authorize: - post: - operationId: DataIntegrationsController_getDataIntegrationAuthorizeUrl - summary: Get authorization URL - description: >- - Generates an OAuth authorization URL to initiate the connection flow for - a user. Redirect the user to the returned URL to begin the OAuth flow - with the third-party provider. - parameters: - - name: slug - required: true - in: path - description: >- - The slug identifier of the provider (e.g., `github`, `slack`, - `notion`). - schema: - example: github - type: string - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - user_id: - type: string - description: The ID of the user to authorize. - example: user_01EHZNVPK3SFK441A1RGBFSHRT - organization_id: - type: string - description: >- - An organization ID to scope the authorization to a specific - organization. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - return_to: - type: string - format: uri - description: The URL to redirect the user to after authorization. - example: https://example.com/callback - required: - - user_id - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DataIntegrationAuthorizeUrlResponse' - '400': - description: Bad Request - 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 - '401': - description: Unauthorized - '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 - tags: - - pipes - /data-integrations/{slug}/token: - post: - operationId: DataIntegrationsController_getUserlandUserToken - summary: Get an access token for a connected account - description: >- - Fetches a valid OAuth access token for a user's connected account. - WorkOS automatically handles token refresh, ensuring you always receive - a valid, non-expired token. - parameters: - - name: slug - required: true - in: path - description: The identifier of the integration. - schema: - example: github - type: string - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - user_id: - type: string - description: A [User](/reference/authkit/user) identifier. - example: user_01EHZNVPK3SFK441A1RGBFSHRT - organization_id: - type: string - description: >- - An [Organization](/reference/organization) identifier. - Optional parameter to scope the connection to a specific - organization. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - user_id - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DataIntegrationAccessTokenResponse' - '400': - description: Bad Request - 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 - '401': - description: Unauthorized - '404': - description: Data integration not found for the given provider slug. - 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 - tags: - - pipes - /directories: - get: - operationId: DirectoriesController_list - summary: List Directories - description: >- - Get a list of all of your existing directories matching the criteria - specified. - 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. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization_id - required: false - in: query - description: Filter Directories by their associated organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: search - required: false - in: query - description: Searchable text to match against Directory names. - schema: - example: Foo Corp - type: string - - name: domain - required: false - in: query - description: Filter Directories by their associated domain. - deprecated: true - schema: - example: foo-corp.com - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DirectoryList' - '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 - '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 - tags: - - directories - /directories/{id}: - get: - operationId: DirectoriesController_find - summary: Get a Directory - description: Get the details of an existing directory. - parameters: - - name: id - required: true - in: path - description: Unique identifier for the Directory. - schema: - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Directory' - '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 - tags: - - directories - delete: - operationId: DirectoriesController_deleteDirectory - summary: Delete a Directory - description: Permanently deletes an existing directory. It cannot be undone. - parameters: - - name: id - required: true - in: path - description: Unique identifier for the Directory. - schema: - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - type: string - responses: - '200': - description: OK - '202': - description: '' - content: - application/json: - schema: {} - '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 - tags: - - directories - /directory_groups: - get: - operationId: DirectoryGroupsController_list - summary: List Directory Groups - description: >- - Get a list of all of existing directory groups matching the criteria - specified. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - 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: user - required: false - in: query - description: >- - Unique identifier of the WorkOS Directory User. This value can be - obtained from the WorkOS API. - schema: - example: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DirectoryGroupList' - '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 - tags: - - directory-groups - /directory_groups/{id}: - get: - operationId: DirectoryGroupsController_find - summary: Get a Directory Group - description: Get the details of an existing Directory Group. - parameters: - - name: id - required: true - in: path - description: Unique identifier for the Directory Group. - schema: - example: directory_group_01E1JJS84MFPPQ3G655FHTKX6Z - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/DirectoryGroup' - '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 - tags: - - directory-groups - /directory_users: - get: - operationId: DirectoryUsersController_list - summary: List Directory Users - description: >- - Get a list of all of existing Directory Users matching the criteria - specified. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - 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 - tags: - - directory-users - /directory_users/{id}: - get: - operationId: DirectoryUsersController_find - summary: Get a Directory User - description: Get the details of an existing Directory User. - 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 - tags: - - directory-users - /events: - get: - operationId: EventsController_list - summary: List events - description: List events for the current environment. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: events - required: false - in: query - description: >- - Filter events by one or more event types (e.g. - `dsync.user.created`). - style: form - explode: false - schema: - example: - - dsync.user.created - - dsync.user.updated - type: array - items: - type: string - - name: range_start - required: false - in: query - description: ISO-8601 date string to filter events created after this date. - schema: - example: '2025-01-01T00:00:00Z' - type: string - - name: range_end - required: false - in: query - description: ISO-8601 date string to filter events created before this date. - schema: - example: '2025-12-31T23:59:59Z' - type: string - - name: organization_id - required: false - in: query - description: >- - Filter events by the [Organization](/reference/organization) that - the event is associated with. - schema: - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/EventList' - '400': - description: Bad Request - 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: - 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: events - required: - - code - - field - description: The list of validation errors. - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - errors - - message - tags: - - events - /feature-flags: - get: - operationId: FeatureFlagsController_list - summary: List feature flags - description: >- - Get a list of all of your existing feature flags matching the criteria - specified. - 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. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/FlagList' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - 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 - tags: - - feature-flags - /feature-flags/{slug}: - get: - operationId: FeatureFlagsController_findBySlug - summary: Get a feature flag - description: Get the details of an existing feature flag by its slug. - parameters: - - name: slug - required: true - in: path - description: A unique key to reference the Feature Flag. - schema: - type: string - example: advanced-analytics - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Flag' - '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 - tags: - - feature-flags - /feature-flags/{slug}/disable: - put: - operationId: FeatureFlagsController_disableFlag - summary: Disable a feature flag - description: Disables a feature flag in the current environment. - parameters: - - name: slug - required: true - in: path - description: A unique key to reference the Feature Flag. - schema: - type: string - example: advanced-analytics - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field does - not need to be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: false - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - x-inline-with-overrides: true - '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 - tags: - - feature-flags - /feature-flags/{slug}/enable: - put: - operationId: FeatureFlagsController_enableFlag - summary: Enable a feature flag - description: Enables a feature flag in the current environment. - parameters: - - name: slug - required: true - in: path - description: A unique key to reference the Feature Flag. - schema: - type: string - example: advanced-analytics - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field does - not need to be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - x-inline-with-overrides: true - '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 - tags: - - feature-flags - /feature-flags/{slug}/targets/{resourceId}: - post: - operationId: FlagTargetsController_createTarget - summary: Add a feature flag target - description: >- - Enables a feature flag for a specific target in the current environment. - Currently, supported targets include users and organizations. - parameters: - - name: resourceId - required: true - in: path - description: The resource ID in format "user_" or "org_". - schema: - example: user_01234567890abcdef - type: string - - name: slug - required: true - in: path - description: The unique slug identifier of the feature flag. - schema: - example: beta-feature - type: string - responses: - '204': - description: Target created or updated successfully. - '400': - description: Invalid resourceId format. - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Invalid resource id - code: - type: string - description: The error code identifying the type of error. - example: invalid_resource_id_format - statusCode: - type: number - description: The HTTP status code. - example: 400 - '403': - description: Access denied. - 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: Feature flag, user, or organization 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 - tags: - - feature-flags.targets - delete: - operationId: FlagTargetsController_deleteTarget - summary: Remove a feature flag target - description: >- - Removes a target from the feature flag's target list in the current - environment. Currently, supported targets include users and - organizations. - parameters: - - name: resourceId - required: true - in: path - description: The resource ID in format "user_" or "org_". - schema: - example: user_01234567890abcdef - type: string - - name: slug - required: true - in: path - description: The unique slug identifier of the feature flag. - schema: - example: beta-feature - type: string - responses: - '204': - description: Target deleted successfully. - '400': - description: Invalid resourceId format. - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Invalid resource id - code: - type: string - description: The error code identifying the type of error. - example: invalid_resource_id_format - statusCode: - type: number - description: The HTTP status code. - example: 400 - '403': - description: Access denied. - 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: Feature flag, user, or organization 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 - tags: - - feature-flags.targets - /organization_domains: - post: - operationId: OrganizationDomainsController_create - summary: Create an Organization Domain - description: Creates a new Organization Domain. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateOrganizationDomainDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - x-inline-with-overrides: true - '409': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - const: domain_already_exists - message: - type: string - description: A human-readable description of the error. - example: Domain already exists for this organization. - required: - - code - - message - tags: - - organization-domains - /organization_domains/{id}: - get: - operationId: OrganizationDomainsController_get - summary: Get an Organization Domain - description: Get the details of an existing organization domain. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the organization domain. - schema: - type: string - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationDomainStandAlone' - '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 - tags: - - organization-domains - delete: - operationId: OrganizationDomainsController_delete - summary: Delete an Organization Domain - description: Permanently deletes an organization domain. It cannot be undone. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the organization domain. - schema: - type: string - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - responses: - '204': - description: Organization domain deleted successfully. - '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 - tags: - - organization-domains - /organization_domains/{id}/verify: - post: - operationId: OrganizationDomainsController_verify - summary: Verify an Organization Domain - description: Initiates verification process for an Organization Domain. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the organization domain. - schema: - type: string - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationDomainStandAlone' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - const: domain_already_verified - message: - type: string - description: A human-readable description of the error. - example: Domain is already verified. - required: - - code - - message - tags: - - organization-domains - /organizations: - get: - operationId: OrganizationsController_list - summary: List Organizations - description: >- - Get a list of all of your existing organizations matching the criteria - specified. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: domains - required: false - in: query - description: >- - The domains of an Organization. Any Organization with a matching - domain will be returned. - style: form - explode: false - schema: - type: array - items: - type: string - example: - - foo-corp.com - - name: search - required: false - in: query - description: >- - Searchable text for an Organization. Matches against the - organization name. - schema: - type: string - example: Acme Corp - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationList' - '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 - tags: - - organizations - post: - operationId: OrganizationsController_create - summary: Create an Organization - description: Creates a new organization in the current environment. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationDto' - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - example: - object: organization - name: Foo Corp - domains: - - object: organization_domain - id: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: org_01HE8GSH8FQPASKSY27THRKRBP - domain: foo-corp.com - state: pending - verification_prefix: superapp-domain-verification-z3kjny - verification_token: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: dns - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - metadata: - tier: diamond - stripe_customer_id: cus_R9qWAGMQ6nGE7V - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - allow_profiles_outside_organization: false - id: org_01EHWNCE74X7JSDV0X3SZ3KJNY - external_id: ext_12345 - description: Created - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_metadata - const: invalid_metadata - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: external_id_already_used - const: external_id_already_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '409': - description: '' - 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 - tags: - - organizations - /organizations/external_id/{external_id}: - get: - operationId: OrganizationsController_getByExternalId - summary: Get an Organization by External ID - description: >- - Get the details of an existing organization by an [external - identifier](/authkit/metadata/external-identifiers). - parameters: - - name: external_id - required: true - in: path - description: The external ID of the Organization. - schema: - type: string - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - '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 - tags: - - organizations - /organizations/{id}: - get: - operationId: OrganizationsController_find - summary: Get an Organization - description: Get the details of an existing organization. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - '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 - tags: - - organizations - put: - operationId: OrganizationsController_updateOrganization - summary: Update an Organization - description: Updates an organization in the current environment. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateOrganizationDto' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - example: - object: organization - name: Foo Corp - domains: - - object: organization_domain - id: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: org_01HE8GSH8FQPASKSY27THRKRBP - domain: foo-corp.com - state: pending - verification_prefix: superapp-domain-verification-z3kjny - verification_token: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: dns - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - metadata: - tier: diamond - stripe_customer_id: cus_R9qWAGMQ6nGE7V - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - allow_profiles_outside_organization: false - id: org_01EHZNVPK3SFK441A1RGBFSHRT - external_id: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - description: OK - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_metadata - const: invalid_metadata - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: external_id_already_used - const: external_id_already_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: stripe_customer_id_already_used - const: stripe_customer_id_already_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - '409': - description: '' - 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 - tags: - - organizations - delete: - operationId: OrganizationsController_deleteOrganization - summary: Delete an Organization - description: >- - Permanently deletes an organization in the current environment. It - cannot be undone. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - responses: - '200': - description: OK - '202': - description: '' - '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 - tags: - - organizations - /organizations/{id}/audit_log_configuration: - get: - operationId: OrganizationsController_getAuditLogConfiguration - summary: Get Audit Log Configuration - description: >- - Get the unified view of audit log trail and stream configuration for an - organization. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogConfiguration' - '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 - tags: - - organizations - /organizations/{id}/audit_logs_retention: - get: - operationId: AuditLogsRetentionController_auditLogsRetention - summary: Get Retention - description: Get the configured event retention period for the given Organization. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogsRetentionJson' - '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 - tags: - - audit-logs - put: - operationId: AuditLogsRetentionController_updateAuditLogsRetention - summary: Set Retention - description: Set the event retention period for the given Organization. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAuditLogsRetentionDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogsRetentionJson' - '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 - tags: - - audit-logs - /organizations/{organizationId}/api_keys: - get: - operationId: OrganizationApiKeysController_list - summary: List API keys for an organization - description: Get a list of all API keys for an organization. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationApiKeyList' - '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 - tags: - - organizations.api_keys - post: - operationId: OrganizationApiKeysController_create - summary: Create an API key for an organization - description: Create a new API key for an organization. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateOrganizationApiKeyDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/OrganizationApiKeyWithValue' - '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: 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 - tags: - - organizations.api_keys - /organizations/{organizationId}/feature-flags: - get: - operationId: OrganizationFeatureFlagsController_list - summary: List enabled feature flags for an organization - description: Get a list of all enabled feature flags for an organization. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/FlagList' - '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 - tags: - - organizations.feature-flags - /organizations/{organizationId}/groups: - post: - operationId: GroupsController_create - summary: Create a group - description: Create a new group within an organization. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateGroupDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/Group' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - get: - operationId: GroupsController_list - summary: List groups - description: Get a paginated list of groups within an organization. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GroupList' - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - /organizations/{organizationId}/groups/{groupId}: - get: - operationId: GroupsController_get - summary: Get a group - description: Retrieve a group by its ID within an organization. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - name: groupId - required: true - in: path - description: The ID of the group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Group' - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - patch: - operationId: GroupsController_update - summary: Update a group - description: >- - Update an existing group. Only the fields provided in the request body - will be updated. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - name: groupId - required: true - in: path - description: The ID of the group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateGroupDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Group' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: bad_request - const: bad_request - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - delete: - operationId: GroupsController_delete - summary: Delete a group - description: Delete a group from an organization. - parameters: - - name: organizationId - required: true - in: path - description: The ID of the organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - name: groupId - required: true - in: path - description: The ID of the group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - responses: - '204': - description: No Content - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - /organizations/{organizationId}/groups/{groupId}/organization-memberships: - post: - operationId: GroupMembershipsController_addMember - summary: Add a member to a Group - description: Add an organization membership to a group. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - name: groupId - required: true - in: path - description: Unique identifier of the Group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateGroupMembershipDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Group' - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - get: - operationId: GroupMembershipsController_listMembers - summary: List Group members - description: Get a list of organization memberships in a group. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - name: groupId - required: true - in: path - description: Unique identifier of the Group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: >- - #/components/schemas/UserlandUserOrganizationMembershipBaseList - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - /organizations/{organizationId}/groups/{groupId}/organization-memberships/{omId}: - delete: - operationId: GroupMembershipsController_removeMember - summary: Remove a member from a Group - description: Remove an organization membership from a group. - parameters: - - name: organizationId - required: true - in: path - description: Unique identifier of the Organization. - schema: - type: string - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - - name: groupId - required: true - in: path - description: Unique identifier of the Group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - - name: omId - required: true - in: path - description: Unique identifier of the Organization Membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - responses: - '204': - description: No Content - '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 - tags: - - groups - x-feature-flag: user-groups-enabled - /portal/generate_link: - post: - operationId: PortalSessionsController_create - summary: Generate a Portal Link - description: Generate a Portal Link scoped to an Organization. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/GenerateLinkDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/PortalLinkResponse' - '400': - description: Bad Request - 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 - '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 - tags: - - admin-portal - /radar/attempts: - post: - operationId: RadarStandaloneController_assess - summary: Create an attempt - description: Assess a request for risk using the Radar engine and receive a verdict. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - ip_address: - type: string - description: The IP address of the request to assess. - example: 49.78.240.97 - user_agent: - type: string - description: The user agent string of the request to assess. - example: Mozilla/5.0 - email: - type: string - format: email - description: The email address of the user making the request. - example: user@example.com - auth_method: - type: string - enum: - - Password - - Passkey - - Authenticator - - SMS_OTP - - Email_OTP - - Social - - SSO - - Other - description: The authentication method being used. - example: Password - action: - type: string - enum: - - login - - signup - - sign-up - - sign-in - - sign_up - - sign_in - - sign in - - sign up - description: The action being performed. - example: login - device_fingerprint: - type: string - description: An optional device fingerprint for the request. - example: fp_abc123 - bot_score: - type: string - description: An optional bot detection score for the request. - example: '0.1' - required: - - ip_address - - user_agent - - email - - auth_method - - action - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/RadarStandaloneResponse' - '400': - description: Standalone radar is not enabled. - 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 - tags: - - radar - /radar/attempts/{id}: - put: - operationId: RadarStandaloneController_updateRadarAttempt - summary: Update a Radar attempt - description: >- - You may optionally inform Radar that an authentication attempt or - challenge was successful using this endpoint. Some Radar controls depend - on tracking recent successful attempts, such as impossible travel. - parameters: - - name: id - required: true - in: path - description: The unique identifier of the Radar attempt to update. - schema: - example: radar_att_01HZBC6N1EB1ZY7KG32X - type: string - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - challenge_status: - type: string - description: Set to `"success"` to mark the challenge as completed. - example: success - const: success - attempt_status: - type: string - description: >- - Set to `"success"` to mark the authentication attempt as - successful. - example: success - const: success - responses: - '204': - description: Radar attempt updated. - '400': - description: Bad Request - 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 - tags: - - radar - /radar/lists/{type}/{action}: - post: - operationId: RadarStandaloneController_updateRadarList - summary: Add an entry to a Radar list - description: Add an entry to a Radar list. - parameters: - - name: type - required: true - in: path - description: The type of the Radar list (e.g. ip_address, domain, email). - schema: - type: string - enum: - - ip_address - - domain - - email - - device - - user_agent - - device_fingerprint - - country - example: ip_address - - name: action - required: true - in: path - description: >- - The list action indicating whether to add the entry to the allow or - block list. - schema: - type: string - enum: - - block - - allow - example: block - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - entry: - type: string - description: >- - The value to add to the list. Must match the format of the - list type (e.g. a valid IP address for `ip_address`, a valid - email for `email`). - example: 198.51.100.42 - required: - - entry - responses: - '200': - description: Entry already present in the list. - content: - application/json: - schema: - $ref: '#/components/schemas/RadarListEntryAlreadyPresentResponse' - '201': - description: Created - '204': - description: Entry successfully added to the list. - '400': - description: Bad Request - 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 - tags: - - radar - delete: - operationId: RadarStandaloneController_deleteRadarListEntry - summary: Remove an entry from a Radar list - description: Remove an entry from a Radar list. - parameters: - - name: type - required: true - in: path - description: The type of the Radar list (e.g. ip_address, domain, email). - schema: - type: string - enum: - - ip_address - - domain - - email - - device - - user_agent - - device_fingerprint - - country - example: ip_address - - name: action - required: true - in: path - description: >- - The list action indicating whether to remove the entry from the - allow or block list. - schema: - type: string - enum: - - block - - allow - example: block - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - entry: - type: string - description: >- - The value to remove from the list. Must match an existing - entry. - example: 198.51.100.42 - required: - - entry - responses: - '204': - description: Radar list updated. - '400': - description: Bad Request - 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 - tags: - - radar - /sso/authorize: - get: - operationId: SsoController_authorize - summary: Initiate SSO - description: Initiates the single sign-on flow. - security: [] - parameters: - - name: provider_scopes - required: false - in: query - description: >- - Additional scopes to request from the identity provider. Applicable - when using OAuth or OpenID Connect connections. - style: form - explode: false - schema: - type: array - items: - type: string - example: - - openid - - profile - - email - - name: provider_query_params - required: false - in: query - description: >- - Key/value pairs of query parameters to pass to the OAuth provider. - Only applicable when using OAuth connections. - schema: - additionalProperties: - type: string - example: - hd: example.com - access_type: offline - type: object - - name: client_id - required: true - in: query - schema: - type: string - example: client_01HZBC6N1EB1ZY7KG32X - description: The unique identifier of the WorkOS environment client. - - name: domain - required: false - in: query - deprecated: true - schema: - type: string - example: example.com - description: >- - Deprecated. Use `connection` or `organization` instead. Used to - initiate SSO for a connection by domain. The domain must be - associated with a connection in your WorkOS environment. - - name: provider - required: false - in: query - schema: - type: string - enum: - - AppleOAuth - - BitbucketOAuth - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - IntuitOAuth - - LinkedInOAuth - - MicrosoftOAuth - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - XeroOAuth - example: GoogleOAuth - description: Used to initiate OAuth authentication with various providers. - - name: redirect_uri - required: true - in: query - schema: - type: string - format: uri - example: https://example.com/callback - description: >- - Where to redirect the user after they complete the authentication - process. You must use one of the redirect URIs configured via the - [Redirects](https://dashboard.workos.com/redirects) page on the - dashboard. - - name: response_type - required: true - in: query - schema: - type: string - example: code - const: code - description: >- - The only valid option for the response type parameter is `"code"`. - - - The `"code"` parameter value initiates an [authorization code grant - type](https://tools.ietf.org/html/rfc6749#section-4.1). This grant - type allows you to exchange an authorization code for an access - token during the redirect that takes place after a user has - authenticated with an identity provider. - - name: state - required: false - in: query - schema: - type: string - example: dj1kUXc0dzlXZ1hjUQ== - description: >- - An optional parameter that can be used to encode arbitrary - information to help restore application state between redirects. If - included, the redirect URI received from WorkOS will contain the - exact `state` that was passed. - - name: connection - required: false - in: query - schema: - type: string - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - description: >- - Used to initiate SSO for a connection. The value should be a WorkOS - connection ID. - - - You can persist the WorkOS connection ID with application user or - team identifiers. WorkOS will use the connection indicated by the - connection parameter to direct the user to the corresponding IdP for - authentication. - - name: organization - required: false - in: query - schema: - type: string - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - description: >- - Used to initiate SSO for an organization. The value should be a - WorkOS organization ID. - - - You can persist the WorkOS organization ID with application user or - team identifiers. WorkOS will use the organization ID to determine - the appropriate connection and the IdP to direct the user to for - authentication. - - name: domain_hint - required: false - in: query - schema: - type: string - example: example.com - description: >- - Can be used to pre-fill the domain field when initiating - authentication with Microsoft OAuth or with a Google SAML connection - type. - - name: login_hint - required: false - in: query - schema: - type: string - example: user@example.com - description: >- - Can be used to pre-fill the username/email address field of the IdP - sign-in page for the user, if you know their username ahead of time. - Currently supported for OAuth, OpenID Connect, Okta, and Entra ID - connections. - - name: nonce - required: false - in: query - schema: - type: string - example: abc123def456 - description: >- - A random string generated by the client that is used to mitigate - replay attacks. - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/SsoAuthorizeUrlResponse' - '302': - headers: - Location: - schema: - type: string - format: uri - description: '' - tags: - - sso - /sso/jwks/{clientId}: - get: - operationId: SsoController_jsonWebKeySet - summary: Get JWKS - description: >- - Returns the JSON Web Key Set (JWKS) containing the public keys used for - verifying access tokens. - parameters: - - name: clientId - required: true - in: path - description: >- - Identifies the application making the request to the WorkOS server. - You can obtain your client ID from the [API - Keys](https://dashboard.workos.com/api-keys) page in the dashboard. - schema: - type: string - example: client_01HXYZ123456789ABCDEFGHIJ - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/JwksResponse' - '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 - tags: - - user-management.session-tokens - /sso/logout: - get: - operationId: SsoController_logout - summary: Logout Redirect - servers: - - url: https://auth.workos.com - description: >- - Logout allows to sign out a user from your application by triggering the - identity provider sign out flow. This `GET` endpoint should be a - redirection, since the identity provider user will be identified in the - browser session. - - - Before redirecting to this endpoint, you need to generate a short-lived - logout token using the [Logout - Authorize](/reference/sso/logout/authorize) endpoint. - security: [] - parameters: - - name: token - required: true - in: query - description: >- - The logout token returned from the [Logout - Authorize](/reference/sso/logout/authorize) endpoint. - schema: - type: string - example: >- - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 - responses: - '200': - description: OK - '302': - headers: - Location: - schema: - type: string - format: uri - description: '' - '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 - tags: - - sso - /sso/logout/authorize: - post: - operationId: SsoController_logoutAuthorize - summary: Logout Authorize - servers: - - url: https://auth.workos.com - description: >- - You should call this endpoint from your server to generate a logout - token which is required for the [Logout Redirect](/reference/sso/logout) - endpoint. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - profile_id: - type: string - description: The unique ID of the profile to log out. - example: prof_01HXYZ123456789ABCDEFGHIJ - required: - - profile_id - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/SsoLogoutAuthorizeResponse' - '201': - description: Created - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - error: - type: string - const: connection_invalid - error_description: - type: string - description: A human-readable description of the error. - example: >- - Single Logout is only supported for GenericOIDC - connections. - required: - - error - - error_description - - type: object - properties: - error: - type: string - const: unauthorized_client - error_description: - type: string - description: A human-readable description of the error. - example: Unauthorized - required: - - error - - error_description - '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 - tags: - - sso - /sso/profile: - get: - operationId: SsoController_getProfile - summary: Get a User Profile - security: - - access_token: [] - description: >- - Exchange an access token for a user's [Profile](/reference/sso/profile). - Because this profile is returned in the [Get a Profile and Token - endpoint](/reference/sso/profile/get-profile-and-token) your application - usually does not need to call this endpoint. It is available for any - authentication flows that require an additional endpoint to retrieve a - user's profile. - parameters: [] - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/Profile' - '401': - description: Unauthorized - content: - application/json: - schema: - type: object - properties: - error: - type: string - const: Unauthorized - required: - - error - '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 - tags: - - sso - /sso/token: - post: - operationId: SsoController_token - summary: Get a Profile and Token - description: >- - Get an access token along with the user - [Profile](/reference/sso/profile) using the code passed to your - [Redirect URI](/reference/sso/get-authorization-url/redirect-uri). - security: [] - parameters: - - name: client_id - required: true - in: query - description: The client ID of the WorkOS environment. - schema: - example: client_01HZBC6N1EB1ZY7KG32X - type: string - - name: client_secret - required: true - in: query - description: The client secret of the WorkOS environment. - schema: - example: sk_example_123456789 - type: string - - name: code - required: true - in: query - description: The authorization code received from the authorization callback. - schema: - example: authorization_code_value - type: string - - name: grant_type - required: true - in: query - description: The grant type for the token request. - schema: - example: authorization_code - type: string - const: authorization_code - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/TokenQueryDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/SsoTokenResponse' - '201': - description: Created - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - error: - type: string - const: invalid_client - error_description: - type: string - description: A human-readable description of the error. - example: Invalid client ID or secret. - required: - - error - - error_description - - type: object - properties: - error: - type: string - const: unauthorized_client - error_description: - type: string - description: A human-readable description of the error. - example: The client is not authorized to use this grant type. - required: - - error - - error_description - - type: object - properties: - error: - type: string - const: invalid_grant - error_description: - type: string - description: A human-readable description of the error. - example: The code has expired or has already been used. - required: - - error - - error_description - - type: object - properties: - error: - type: string - const: unsupported_grant_type - error_description: - type: string - description: A human-readable description of the error. - example: The grant type is not supported. - required: - - error - - error_description - '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 - tags: - - sso - /user_management/authenticate: - post: - operationId: UserlandSessionsController_authenticate - summary: Authenticate - description: >- - Authenticate a user with a specified [authentication - method](/reference/authkit/authentication). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - oneOf: - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: authorization_code - code: - type: string - description: The authorization code received from the redirect. - example: vBqZKaPpsnJlPfXiDqN7b6VTz - code_verifier: - type: string - description: >- - The PKCE code verifier used to derive the code challenge - passed to the authorization URL. - example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk - invitation_token: - type: string - description: An invitation token to accept during authentication. - example: inv_tok_01HXYZ123456789ABCDEFGHIJ - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - code - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: password - email: - type: string - description: The user's email address. - example: user@example.com - password: - type: string - description: The user's password. - example: strong_password_123! - invitation_token: - type: string - description: An invitation token to accept during authentication. - example: inv_tok_01HXYZ123456789ABCDEFGHIJ - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - email - - password - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: refresh_token - refresh_token: - type: string - description: The refresh token to exchange for new tokens. - example: yAjhKk23hJMM3DaR... - organization_id: - type: string - description: The ID of the organization to scope the session to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - refresh_token - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: urn:workos:oauth:grant-type:magic-auth:code - code: - type: string - description: The one-time code for Magic Auth authentication. - example: '123456' - email: - type: string - description: The user's email address. - example: user@example.com - invitation_token: - type: string - description: An invitation token to accept during authentication. - example: inv_tok_01HXYZ123456789ABCDEFGHIJ - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - code - - email - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: urn:workos:oauth:grant-type:email-verification:code - code: - type: string - description: The email verification code. - example: '123456' - pending_authentication_token: - type: string - description: >- - The pending authentication token from a previous - authentication attempt. - example: cTDQJTTkTkkVYxbn... - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - code - - pending_authentication_token - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: urn:workos:oauth:grant-type:mfa-totp - code: - type: string - description: The TOTP code from the authenticator app. - example: '123456' - pending_authentication_token: - type: string - description: >- - The pending authentication token from a previous - authentication attempt. - example: cTDQJTTkTkkVYxbn... - authentication_challenge_id: - type: string - description: The ID of the MFA authentication challenge. - example: auth_challenge_01HXYZ123456789ABCDEFGHIJ - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - code - - pending_authentication_token - - authentication_challenge_id - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - client_secret: - type: string - description: The client secret of the application. - example: sk_test_.... - grant_type: - type: string - const: urn:workos:oauth:grant-type:organization-selection - pending_authentication_token: - type: string - description: >- - The pending authentication token from a previous - authentication attempt. - example: cTDQJTTkTkkVYxbn... - organization_id: - type: string - description: The ID of the organization the user selected. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - client_secret - - grant_type - - pending_authentication_token - - organization_id - - type: object - properties: - client_id: - type: string - description: The client ID of the application. - example: client_01HXYZ123456789ABCDEFGHIJ - grant_type: - type: string - const: urn:ietf:params:oauth:grant-type:device_code - device_code: - type: string - description: The device verification code. - example: Ao4fMrDS... - ip_address: - type: string - description: The IP address of the user's request. - example: 203.0.113.42 - device_id: - type: string - description: A unique identifier for the device. - example: device_01HXYZ123456789ABCDEFGHIJ - user_agent: - type: string - description: The user agent string from the user's browser. - example: Mozilla/5.0 - required: - - client_id - - grant_type - - device_code - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandAuthenticateResponse' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_organization_id - const: invalid_organization_id - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: code_challenge_not_found - const: code_challenge_not_found - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_credentials - const: invalid_credentials - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_one_time_code - const: invalid_one_time_code - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: one_time_code_previously_used - const: one_time_code_previously_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: one_time_code_expired - const: one_time_code_expired - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: one_time_code_too_many_attempts - const: one_time_code_too_many_attempts - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_pending_authentication_token - const: invalid_pending_authentication_token - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: user_mismatch - const: user_mismatch - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invalid_client - const: invalid_client - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invalid_client.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: unauthorized_client - const: unauthorized_client - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: unauthorized_client.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invalid_profile - const: invalid_profile - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invalid_profile.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invitation_invalid - const: invitation_invalid - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invitation_invalid.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invitation_cannot_be_used_for_email - const: invitation_cannot_be_used_for_email - error_description: - type: string - description: A human-readable description of the error. - example: >- - The request failed due to: - invitation_cannot_be_used_for_email. - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: authentication_method_not_allowed - const: authentication_method_not_allowed - error_description: - type: string - description: A human-readable description of the error. - example: >- - The request failed due to: - authentication_method_not_allowed. - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invalid_connection - const: invalid_connection - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invalid_connection.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: sign_up_not_allowed - const: sign_up_not_allowed - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: sign_up_not_allowed.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: organization_authentication_methods_required - const: organization_authentication_methods_required - error_description: - type: string - description: A human-readable description of the error. - example: >- - The request failed due to: - organization_authentication_methods_required. - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invalid_link_authorization_code - const: invalid_link_authorization_code - error_description: - type: string - description: A human-readable description of the error. - example: >- - The request failed due to: - invalid_link_authorization_code. - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: extra_attributes_required - const: extra_attributes_required - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: extra_attributes_required.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: pkce_not_supported - const: pkce_not_supported - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: pkce_not_supported.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: expired_token - const: expired_token - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: expired_token.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: authorization_pending - const: authorization_pending - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: authorization_pending.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: access_denied - const: access_denied - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: access_denied.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: slow_down - const: slow_down - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: slow_down.' - required: - - error - - error_description - - type: object - properties: - message: - type: string - const: Must use SSO for selected organization - required: - - message - - oneOf: - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invalid_grant - const: invalid_grant - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invalid_grant.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invalid_request - const: invalid_request - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invalid_request.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: organization_not_found - const: organization_not_found - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: organization_not_found.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: organization_membership_not_found - const: organization_membership_not_found - error_description: - type: string - description: A human-readable description of the error. - example: >- - The request failed due to: - organization_membership_not_found. - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: mfa_enrollment - const: mfa_enrollment - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: mfa_enrollment.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: token_too_big - const: token_too_big - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: token_too_big.' - required: - - error - - error_description - - allOf: - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: sso_required - const: sso_required - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: sso_required.' - required: - - error - - error_description - - type: object - properties: - connection_ids: - type: array - items: - type: string - example: conn_01FVYZ... - description: >- - The IDs of the SSO connections the user must - authenticate through. - email: - type: string - description: >- - The email address of the user that must - authenticate via SSO. - example: user@example.com - required: - - connection_ids - - email - '403': - description: Forbidden - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: mfa_enrollment - const: mfa_enrollment - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: mfa_challenge - const: mfa_challenge - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: authentication_method_not_allowed - const: authentication_method_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_required - const: email_verification_required - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_password_auth_disabled - const: email_password_auth_disabled - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: organization_selection_required - const: organization_selection_required - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: passkey_progressive_enrollment - const: passkey_progressive_enrollment - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: radar_challenge - const: radar_challenge - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: radar_sign_up_challenge - const: radar_sign_up_challenge - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: application_consent_required - const: application_consent_required - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - '429': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - user-management.authentication - /user_management/authorize: - get: - operationId: UserlandSsoController_authorize - summary: Get an authorization URL - description: >- - Generates an OAuth 2.0 authorization URL to authenticate a user with - AuthKit or SSO. - security: [] - parameters: - - name: code_challenge_method - required: false - in: query - schema: - type: string - example: S256 - const: S256 - description: >- - The only valid PKCE code challenge method is `"S256"`. Required when - specifying a `code_challenge`. - - name: code_challenge - required: false - in: query - schema: - type: string - example: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM - description: >- - Code challenge derived from the code verifier used for the PKCE - flow. - - name: domain_hint - required: false - in: query - schema: - type: string - example: example.com - description: A domain hint for SSO connection lookup. - - name: connection_id - required: false - in: query - schema: - type: string - example: conn_01EHQMYV6MBK39QC5PZXHY59C3 - description: The ID of an SSO connection to use for authentication. - - name: provider_query_params - required: false - in: query - schema: - type: object - additionalProperties: - type: string - example: - hd: example.com - access_type: offline - description: Key/value pairs of query parameters to pass to the OAuth provider. - - name: provider_scopes - required: false - in: query - style: form - explode: false - schema: - type: array - items: - type: string - example: - - openid - - profile - - email - description: Additional OAuth scopes to request from the identity provider. - - name: invitation_token - required: false - in: query - schema: - type: string - example: inv_token_abc123 - description: >- - A token representing a user invitation to redeem during - authentication. - - name: screen_hint - required: false - in: query - schema: - type: string - enum: - - sign-up - - sign-in - default: sign-in - example: sign-in - description: >- - Used to specify which screen to display when the provider is - `authkit`. - - name: login_hint - required: false - in: query - schema: - type: string - example: user@example.com - description: >- - A hint to the authorization server about the login identifier the - user might use. - - name: provider - required: false - in: query - schema: - type: string - enum: - - authkit - - AppleOAuth - - BitbucketOAuth - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - IntuitOAuth - - LinkedInOAuth - - MicrosoftOAuth - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - XeroOAuth - example: GoogleOAuth - description: >- - The OAuth provider to authenticate with (e.g., GoogleOAuth, - MicrosoftOAuth, GitHubOAuth). - - name: prompt - required: false - in: query - schema: - type: string - example: login - description: Controls the authentication flow behavior for the user. - - name: state - required: false - in: query - schema: - type: string - example: eyJyZXR1cm5UbyI6ICIvZGFzaGJvYXJkIn0= - description: >- - An opaque value used to maintain state between the request and the - callback. - - name: organization_id - required: false - in: query - schema: - type: string - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - description: The ID of the organization to authenticate the user against. - - name: response_type - required: true - in: query - schema: - type: string - example: code - const: code - description: The response type of the application. - - name: redirect_uri - required: true - in: query - schema: - type: string - format: uri - example: https://example.com/callback - description: >- - The callback URI where the authorization code will be sent after - authentication. - - name: client_id - required: true - in: query - schema: - type: string - example: client_01HZBC6N1EB1ZY7KG32X - description: The unique identifier of the WorkOS environment client. - responses: - '200': - headers: - location: - schema: - type: string - format: uri - description: OK - '302': - headers: - location: - schema: - type: string - format: uri - description: '' - tags: - - user-management.authentication - /user_management/authorize/device: - post: - operationId: UserlandSsoController_deviceAuthorization - summary: Get device authorization URL - description: >- - Initiates the CLI Auth flow by requesting a device code and verification - URLs. This endpoint implements the OAuth 2.0 Device Authorization Flow - ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) and is - designed for command-line applications or other devices with limited - input capabilities. - security: [] - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - type: object - properties: - client_id: - type: string - description: The WorkOS client ID for your application. - example: client_01HZBC6N1EB1ZY7KG32X - required: - - client_id - responses: - '200': - description: Device authorization response with codes and verification URI. - content: - application/json: - schema: - $ref: '#/components/schemas/DeviceAuthorizationResponse' - '400': - description: Invalid request parameters. - content: - application/json: - schema: - type: object - properties: - error: - type: string - description: Error code. - example: invalid_client - error_description: - type: string - description: Human-readable error description. - example: Unknown client - required: - - error - - error_description - '403': - description: Feature not enabled for team. - content: - application/json: - schema: - type: object - properties: - error: - type: string - description: Error code. - example: access_denied - error_description: - type: string - description: Human-readable error description. - example: Device authorization grant is not enabled for this team - required: - - error - - error_description - tags: - - user-management.authentication - /user_management/cors_origins: - post: - operationId: CorsOriginsController_createCorsOrigin - summary: Create a CORS origin - description: >- - Creates a new CORS origin for the current environment. CORS origins - allow browser-based applications to make requests to the WorkOS API. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateCorsOriginDto' - responses: - '201': - description: CORS origin created successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/CorsOriginResponse' - '409': - description: Duplicate CORS origin. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code. - example: duplicate_cors_origin - message: - type: string - description: A human-readable error message. - example: CORS origin already exists. - '422': - description: Validation error. - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable error message. - example: Validation failed. - errors: - type: array - description: The list of validation errors. - items: - type: object - properties: - property: - type: string - description: The property that failed validation. - example: origin - constraints: - type: object - tags: - - user-management.cors-origins - /user_management/email_verification/{id}: - get: - operationId: UserlandUsersController_getEmailVerification - summary: Get an email verification code - description: >- - Get the details of an existing email verification code that can be used - to send an email to a user for verification. - parameters: - - name: id - required: true - in: path - description: The ID of the email verification code. - schema: - type: string - example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/EmailVerification' - '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 - tags: - - user-management.users - /user_management/invitations: - get: - operationId: UserlandUserInvitesController_list - summary: List invitations - description: Get a list of all of invitations matching the criteria specified. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization_id - required: false - in: query - description: >- - The ID of the [organization](/reference/organization) that the - recipient will join. - schema: - example: org_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - name: email - required: false - in: query - description: The email address of the recipient. - schema: - example: marcelina.davis@example.com - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - allOf: - - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - 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: invitation_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: invitation_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - - type: object - properties: - data: - type: array - description: The list of records for the current page. - items: - $ref: '#/components/schemas/UserlandUserInvite' - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.invitations - post: - operationId: UserlandUserInvitesController_create - summary: Send an invitation - description: Sends an invitation email to the recipient. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserlandUserInviteOptionsDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserInvite' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_already_invited_to_organization - const: email_already_invited_to_organization - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: user_already_organization_member - const: user_already_organization_member - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_already_invited - const: email_already_invited - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: user_already_exists - const: user_already_exists - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: expires_in_days_too_short - const: expires_in_days_too_short - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: expires_in_days_too_long - const: expires_in_days_too_long - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_role - const: invalid_role - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.invitations - x-sends-email: true - /user_management/invitations/by_token/{token}: - get: - operationId: UserlandUserInvitesController_getByToken - summary: Find an invitation by token - description: Retrieve an existing invitation using the token. - parameters: - - name: token - required: true - in: path - description: The token used to accept the invitation. - schema: - example: Z1uX3RbwcIl5fIGJJJCXXisdI - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserInvite' - '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 - tags: - - user-management.invitations - /user_management/invitations/{id}: - get: - operationId: UserlandUserInvitesController_get - summary: Get an invitation - description: Get the details of an existing invitation. - parameters: - - name: id - required: true - in: path - description: The unique ID of the invitation. - schema: - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserInvite' - '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 - tags: - - user-management.invitations - /user_management/invitations/{id}/accept: - post: - operationId: UserlandUserInvitesController_accept - summary: Accept an invitation - description: >- - Accepts an invitation and, if linked to an organization, activates the - user's membership in that organization. - parameters: - - name: id - required: true - in: path - description: The unique ID of the invitation. - schema: - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: accepted - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if - not yet accepted. - example: '2026-01-15T12:00:00.000Z' - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if - not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that - the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on - acceptance. Reflects the current role on the invitee's - organization membership. null when the invitation has no - associated organization. - example: admin - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - - token - - accept_invitation_url - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - enum: - - invite_not_pending - - invalid_invite - - invite_has_accepted_user_id - message: - type: string - description: A human-readable description of the error. - example: Invite is not pending. - required: - - code - - 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 - tags: - - user-management.invitations - /user_management/invitations/{id}/resend: - post: - operationId: UserlandUserInvitesController_resend - summary: Resend an invitation - description: >- - Resends an invitation email to the recipient. The invitation must be in - a pending state. - parameters: - - name: id - required: true - in: path - description: The unique ID of the invitation. - schema: - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/ResendUserlandUserInviteOptionsDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserInvite' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - const: invite_expired - message: - type: string - description: A human-readable description of the error. - example: Invite has expired. - required: - - code - - message - - type: object - properties: - code: - type: string - const: invite_revoked - message: - type: string - description: A human-readable description of the error. - example: Invite has been revoked. - required: - - code - - message - - type: object - properties: - code: - type: string - const: invite_accepted - message: - type: string - description: A human-readable description of the error. - example: Invite has already been accepted. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.invitations - x-sends-email: true - /user_management/invitations/{id}/revoke: - post: - operationId: UserlandUserInvitesController_revoke - summary: Revoke an invitation - description: Revokes an existing invitation. - parameters: - - name: id - required: true - in: path - description: The unique ID of the invitation. - schema: - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: revoked - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if - not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if - not revoked. - example: '2026-01-15T12:00:00.000Z' - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that - the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on - acceptance. Reflects the current role on the invitee's - organization membership. null when the invitation has no - associated organization. - example: admin - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - - token - - accept_invitation_url - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invite_not_pending - const: invite_not_pending - message: - type: string - description: A human-readable description of the error. - example: Invite is not pending. - required: - - code - - message - tags: - - user-management.invitations - /user_management/jwt_template: - get: - operationId: JwtTemplatesController_getJwtTemplate - summary: Get JWT template - description: Get the JWT template for the current environment. - parameters: [] - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/JwtTemplate' - '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 - tags: - - user-management.jwt-template - put: - operationId: JwtTemplatesController_updateJwtTemplate - summary: Update JWT template - description: Update the JWT template for the current environment. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateJwtTemplateDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/JwtTemplate' - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.jwt-template - /user_management/magic_auth: - post: - operationId: UserlandMagicAuthController_sendMagicAuthCodeAndReturn - summary: Create a Magic Auth code - description: >- - Creates a one-time authentication code that can be sent to the user's - email address. The code expires in 10 minutes. To verify the code, - [authenticate the user with Magic - Auth](/reference/authkit/authentication/magic-auth). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserlandMagicCodeAndReturnDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/MagicAuth' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: invitation_invalid - const: invitation_invalid - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: invitation_invalid.' - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: authentication_method_not_allowed - const: authentication_method_not_allowed - error_description: - type: string - description: A human-readable description of the error. - example: >- - The request failed due to: - authentication_method_not_allowed. - required: - - error - - error_description - - type: object - properties: - error: - type: string - description: The OAuth error code. - example: sign_up_not_allowed - const: sign_up_not_allowed - error_description: - type: string - description: A human-readable description of the error. - example: 'The request failed due to: sign_up_not_allowed.' - required: - - error - - error_description - '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: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - user-management.magic-auth - x-sends-email: true - /user_management/magic_auth/{id}: - get: - operationId: UserlandMagicAuthController_get - summary: Get Magic Auth code details - description: >- - Get the details of an existing [Magic - Auth](/reference/authkit/magic-auth) code that can be used to send an - email to a user for authentication. - parameters: - - name: id - required: true - in: path - description: The unique ID of the Magic Auth code. - schema: - example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/MagicAuth' - '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 - tags: - - user-management.magic-auth - /user_management/organization_memberships: - get: - operationId: UserlandUserOrganizationMembershipsController_list - summary: List organization memberships - description: >- - Get a list of all organization memberships matching the criteria - specified. At least one of `user_id` or `organization_id` must be - provided. By default only active memberships are returned. Use the - `statuses` parameter to filter by other statuses. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization_id - required: false - in: query - description: >- - The ID of the [organization](/reference/organization) which the user - belongs to. - schema: - example: org_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - name: statuses - required: false - in: query - description: >- - Filter by the status of the organization membership. Array including - any of `active`, `inactive`, or `pending`. - style: form - explode: false - schema: - example: - - active - type: array - items: - type: string - enum: - - active - - inactive - - pending - - name: user_id - required: false - in: query - description: The ID of the [user](/reference/authkit/user). - schema: - example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - allOf: - - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - 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: om_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: om_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - - type: object - properties: - data: - type: array - description: The list of records for the current page. - items: - $ref: >- - #/components/schemas/UserlandUserOrganizationMembership - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: missing_user_id_or_organization_id - const: missing_user_id_or_organization_id - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - tags: - - user-management.organization-membership - post: - operationId: UserlandUserOrganizationMembershipsController_create - summary: Create an organization membership - description: >- - Creates a new `active` organization membership for the given - organization and user. - - - Calling this API with an organization and user that match an `inactive` - organization membership will activate the membership with the specified - role(s). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserlandUserOrganizationMembershipDto' - responses: - '201': - description: Created - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - role: - $ref: '#/components/schemas/SlimRole' - description: >- - The primary role assigned to the user within the - organization. - user: - $ref: '#/components/schemas/UserlandUser' - description: >- - The user that belongs to the organization through this - membership. - required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role - - user - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - A pending organization membership cannot be reactivated. - The user needs to accept the invitation instead. - code: - type: string - description: The error code identifying the type of error. - example: cannot_reactivate_pending_organization_membership - const: cannot_reactivate_pending_organization_membership - required: - - message - - code - '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: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Role 'invalid_slug' is not a valid role. - code: - type: string - description: The error code identifying the type of error. - example: invalid_role - const: invalid_role - required: - - message - - code - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Multiple roles are not enabled for this environment. - code: - type: string - description: The error code identifying the type of error. - example: multiple_roles_not_enabled - const: multiple_roles_not_enabled - required: - - message - - code - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Sub-resource scoped roles are not allowed for this - operation. - code: - type: string - description: The error code identifying the type of error. - example: sub_resource_scoped_role_not_allowed - const: sub_resource_scoped_role_not_allowed - role_slug: - type: string - description: The slug of the role that is not allowed. - example: admin - required: - - message - - code - - role_slug - tags: - - user-management.organization-membership - x-mutually-exclusive-body-groups: &ref_9 - role: - optional: true - variants: - single: - - role_slug - multiple: - - role_slugs - /user_management/organization_memberships/{id}: - get: - operationId: UserlandUserOrganizationMembershipsController_get - summary: Get an organization membership - description: Get the details of an existing organization membership. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserOrganizationMembership' - '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 - tags: - - user-management.organization-membership - delete: - operationId: UserlandUserOrganizationMembershipsController_delete - summary: Delete an organization membership - description: >- - Permanently deletes an existing organization membership. It cannot be - undone. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - responses: - '200': - description: OK - '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 - tags: - - user-management.organization-membership - put: - operationId: UserlandUserOrganizationMembershipsController_update - summary: Update an organization membership - description: Update the details of an existing organization membership. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateUserlandUserOrganizationMembershipDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserOrganizationMembership' - '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: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Role 'invalid_slug' is not a valid role. - code: - type: string - description: The error code identifying the type of error. - example: invalid_role - const: invalid_role - required: - - message - - code - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: Multiple roles are not enabled for this environment. - code: - type: string - description: The error code identifying the type of error. - example: multiple_roles_not_enabled - const: multiple_roles_not_enabled - required: - - message - - code - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Sub-resource scoped roles are not allowed for this - operation. - code: - type: string - description: The error code identifying the type of error. - example: sub_resource_scoped_role_not_allowed - const: sub_resource_scoped_role_not_allowed - role_slug: - type: string - description: The slug of the role that is not allowed. - example: admin - required: - - message - - code - - role_slug - tags: - - user-management.organization-membership - x-mutually-exclusive-body-groups: &ref_10 - role: - optional: true - variants: - single: - - role_slug - multiple: - - role_slugs - /user_management/organization_memberships/{id}/deactivate: - put: - operationId: UserlandUserOrganizationMembershipsController_deactivate - summary: Deactivate an organization membership - description: >- - Deactivates an `active` organization membership. Emits an - [organization_membership.updated](/events/organization-membership) event - upon successful deactivation. - - - - Deactivating an `inactive` membership is a no-op and does not emit an - event. - - - Deactivating a `pending` membership returns an error. This membership - should be [deleted](/reference/authkit/organization-membership/delete) - instead. - - - See the [membership management - documentation](/authkit/users-organizations/organizations/membership-management) - for additional details. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of - `active`, `inactive`, or `pending`. - example: inactive - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a - directory sync connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the - linked [Directory - User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - role: - $ref: '#/components/schemas/SlimRole' - description: >- - The primary role assigned to the user within the - organization. - user: - $ref: '#/components/schemas/UserlandUser' - description: >- - The user that belongs to the organization through this - membership. - required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role - - user - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - A pending organization membership cannot be deactivated. - This membership should be deleted instead. - code: - type: string - description: The error code identifying the type of error. - example: cannot_deactivate_pending_organization_membership - const: cannot_deactivate_pending_organization_membership - required: - - message - - code - '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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.organization-membership - /user_management/organization_memberships/{id}/reactivate: - put: - operationId: UserlandUserOrganizationMembershipsController_reactivate - summary: Reactivate an organization membership - description: >- - Reactivates an `inactive` organization membership, retaining the - pre-existing role(s). Emits an - [organization_membership.updated](/events/organization-membership) event - upon successful reactivation. - - - - Reactivating an `active` membership is a no-op and does not emit an - event. - - - Reactivating a `pending` membership returns an error. The user needs - to [accept the invitation](/authkit/invitations) instead. - - - See the [membership management - documentation](/authkit/users-organizations/organizations/membership-management) - for additional details. - parameters: - - name: id - required: true - in: path - description: The unique ID of the organization membership. - schema: - example: om_01HXYZ123456789ABCDEFGHIJ - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserOrganizationMembership' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - A pending organization membership cannot be reactivated. - The user needs to accept the invitation instead. - code: - type: string - description: The error code identifying the type of error. - example: cannot_reactivate_pending_organization_membership - const: cannot_reactivate_pending_organization_membership - required: - - message - - code - '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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.organization-membership - /user_management/organization_memberships/{omId}/groups: - get: - operationId: OrganizationMembershipGroupsController_listGroups - summary: List groups - description: Get a list of groups that an organization membership belongs to. - parameters: - - name: omId - required: true - in: path - description: Unique identifier of the Organization Membership. - schema: - type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GroupList' - '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 - tags: - - user-management.organization-membership.groups - x-feature-flag: user-groups-enabled - /user_management/password_reset: - post: - operationId: UserlandUsersController_createPasswordResetToken - summary: Create a password reset token - description: Creates a one-time token that can be used to reset a user's password. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreatePasswordResetTokenDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordReset' - '403': - description: Forbidden - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_password_auth_disabled - const: email_password_auth_disabled - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_reset_not_allowed - const: password_reset_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - '429': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - user-management.users - x-sends-email: true - /user_management/password_reset/confirm: - post: - operationId: UserlandUsersController_resetPassword - summary: Reset the password - description: >- - Sets a new password using the `token` query parameter from the link that - the user received. Successfully resetting the password will verify a - user's email, if it hasn't been verified yet. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreatePasswordResetDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ResetPasswordResponse' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_reset_error - const: password_reset_error - 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: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - '403': - description: Forbidden - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_password_auth_disabled - const: email_password_auth_disabled - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.users - /user_management/password_reset/{id}: - get: - operationId: UserlandUsersController_getPasswordReset - summary: Get a password reset token - description: >- - Get the details of an existing password reset token that can be used to - reset a user's password. - parameters: - - name: id - required: true - in: path - description: The ID of the password reset token. - schema: - type: string - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordReset' - '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 - tags: - - user-management.users - /user_management/redirect_uris: - post: - operationId: RedirectUrisController_create - summary: Create a redirect URI - description: Creates a new redirect URI for an environment. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateRedirectUriDto' - responses: - '201': - description: Redirect URI created successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/RedirectUri' - example: - object: redirect_uri - id: ruri_01EHZNVPK3SFK441A1RGBFSHRT - uri: https://example.com/callback - default: true - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - '400': - description: Bad Request - 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 - example: - message: Bad Request - '401': - description: Unauthorized - 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 - example: - message: Unauthorized - '422': - description: Validation failed. - 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 - example: - message: Redirect URI 'https://example.com/callback' already exists. - tags: - - user-management.redirect-uris - /user_management/sessions/logout: - get: - operationId: UserlandSessionsController_logout - summary: Logout - security: [] - description: Logout a user from the current [session](/reference/authkit/session). - parameters: - - name: session_id - required: true - in: query - description: >- - The ID of the session to revoke. This can be extracted from the - `sid` claim of the access token. - schema: - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - type: string - - name: return_to - required: false - in: query - description: The URL to redirect the user to after session revocation. - schema: - example: https://example.com - type: string - responses: - '200': - headers: - location: - schema: - type: string - format: uri - description: OK - '302': - headers: - location: - schema: - type: string - format: uri - description: '' - '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 - tags: - - user-management.authentication - /user_management/sessions/revoke: - post: - operationId: UserlandSessionsController_revokeSession - summary: Revoke Session - description: Revoke a [user session](/reference/authkit/session). - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandRevokeSessionDto' - responses: - '200': - description: OK - '400': - description: Bad Request - 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 - tags: - - user-management.authentication - /user_management/users: - get: - operationId: UserlandUsersController_list - summary: List users - description: >- - Get a list of all of your existing users matching the criteria - specified. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - name: organization - required: false - in: query - deprecated: true - description: >- - Filter users by the organization they are a member of. Deprecated in - favor of `organization_id`. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: organization_id - required: false - in: query - description: Filter users by the organization they are a member of. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: email - required: false - in: query - description: Filter users by their email address. - schema: - example: user@example.com - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserList' - '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 - tags: - - user-management.users - post: - operationId: UserlandUsersController_create - summary: Create a user - description: Create a new user in the current environment. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateUserlandUserDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUser' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_strength_error - const: password_strength_error - 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: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: user_creation_error - const: user_creation_error - 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: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_password_hash - const: invalid_password_hash - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_provided - const: password_and_password_hash_provided - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_type_provided - const: password_and_password_hash_type_provided - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_metadata - const: invalid_metadata - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.users - x-mutually-exclusive-body-groups: &ref_11 - password: - optional: true - variants: - plaintext: - - password - hashed: - - password_hash - - password_hash_type - /user_management/users/external_id/{external_id}: - get: - operationId: UserlandUsersController_getByExternalId - summary: Get a user by external ID - description: >- - Get the details of an existing user by an [external - identifier](/authkit/metadata/external-identifiers). - parameters: - - name: external_id - required: true - in: path - description: The external ID of the user. - schema: - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUser' - '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 - tags: - - user-management.users - /user_management/users/{id}: - put: - operationId: UserlandUsersController_update - summary: Update a user - description: >- - Updates properties of a user. The omitted properties will be left - unchanged. - parameters: - - name: id - required: true - in: path - description: The unique ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateUserlandUserDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUser' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_strength_error - const: password_strength_error - 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: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_password_hash - const: invalid_password_hash - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_provided - const: password_and_password_hash_provided - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: password_and_password_hash_type_provided - const: password_and_password_hash_type_provided - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_already_verified - const: email_already_verified - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_metadata - const: invalid_metadata - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: external_id_already_used - const: external_id_already_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_not_allowed - const: email_change_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_not_available - const: email_not_available - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_email - const: invalid_email - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_locale - const: invalid_locale - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.users - x-mutually-exclusive-body-groups: &ref_14 - password: - optional: true - variants: - plaintext: - - password - hashed: - - password_hash - - password_hash_type - get: - operationId: UserlandUsersController_get - summary: Get a user - description: Get the details of an existing user. - parameters: - - name: id - required: true - in: path - description: The unique ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUser' - '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 - tags: - - user-management.users - delete: - operationId: UserlandUsersController_delete - summary: Delete a user - description: >- - Permanently deletes a user in the current environment. It cannot be - undone. - parameters: - - name: id - required: true - in: path - description: The unique ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - '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 - tags: - - user-management.users - /user_management/users/{id}/email_change/confirm: - post: - operationId: UserlandUsersController_confirmEmailChange - summary: Confirm email change - description: Confirms an email change using the one-time code received by the user. - parameters: - - name: id - required: true - in: path - description: The unique ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/ConfirmEmailChangeDto' - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - object: - type: string - description: Distinguishes the email change confirmation object. - const: email_change_confirmation - user: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - 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 - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: new.email@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing metadata key/value pairs associated - with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - description: The user object. - required: - - object - - user - x-inline-with-overrides: true - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_code_expired - const: email_change_code_expired - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_code_incorrect - const: email_change_code_incorrect - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - '409': - description: '' - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: no_pending_email_change - const: no_pending_email_change - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_code_previously_used - const: email_change_code_previously_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_not_available - const: email_not_available - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_not_allowed - const: email_change_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_email - const: invalid_email - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '429': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_too_many_attempts - const: email_change_too_many_attempts - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - user-management.users - /user_management/users/{id}/email_change/send: - post: - operationId: UserlandUsersController_sendEmailChange - summary: Send email change code - description: >- - Sends an email that contains a one-time code used to change a user's - email address. - parameters: - - name: id - required: true - in: path - description: The unique ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/SendEmailChangeDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/EmailChange' - '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 - '409': - description: '' - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_not_needed - const: email_change_not_needed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_not_available - const: email_not_available - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_change_not_allowed - const: email_change_not_allowed - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_email - const: invalid_email - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '429': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - user-management.users - x-sends-email: true - /user_management/users/{id}/email_verification/confirm: - post: - operationId: UserlandUsersController_emailVerification - summary: Verify email - description: Verifies an email address using the one-time code received by the user. - parameters: - - name: id - required: true - in: path - description: The ID of the user. - schema: - type: string - example: user_01E4ZCR3C56J083X43JQXF3JK5 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/VerifyEmailAddressDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/VerifyEmailResponse' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_previously_verified - const: email_previously_verified - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_code_previously_used - const: email_verification_code_previously_used - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_code_expired - const: email_verification_code_expired - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_verification_code_incorrect - const: email_verification_code_incorrect - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.users - /user_management/users/{id}/email_verification/send: - post: - operationId: UserlandUsersController_sendVerificationEmail - summary: Send verification email - description: >- - Sends an email that contains a one-time code used to verify a user’s - email address. - parameters: - - name: id - required: true - in: path - description: The ID of the user. - schema: - type: string - example: user_01E4ZCR3C56J083X43JQXF3JK5 - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/SendVerificationEmailResponse' - '400': - description: Bad Request - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: email_already_verified - const: email_already_verified - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - 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 - '429': - description: '' - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: daily_quota_exceeded - const: daily_quota_exceeded - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - user-management.users - /user_management/users/{id}/identities: - get: - operationId: UserlandUserIdentitiesController_get - summary: Get user identities - description: >- - Get a list of identities associated with the user. A user can have - multiple associated identities after going through [identity - linking](/authkit/identity-linking). Currently only OAuth identities are - supported. More provider types may be added in the future. - parameters: - - name: id - required: true - in: path - description: The unique ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: array - items: - type: object - properties: - idp_id: - type: string - description: >- - The unique ID of the user in the external identity - provider. - example: 4F42ABDE-1E44-4B66-824A-5F733C037A6D - type: - type: string - description: The type of the identity. - const: OAuth - provider: - type: string - enum: - - AppleOAuth - - BitbucketOAuth - - DiscordOAuth - - GithubOAuth - - GitLabOAuth - - GoogleOAuth - - IntuitOAuth - - LinkedInOAuth - - MicrosoftOAuth - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - XeroOAuth - description: The type of OAuth provider for the identity. - example: MicrosoftOAuth - required: - - idp_id - - type - - provider - '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 - tags: - - user-management.users - /user_management/users/{id}/sessions: - get: - operationId: UserlandUserSessionsController_list - summary: List sessions - description: Get a list of all active sessions for a specific user. - parameters: - - name: id - required: true - in: path - description: The ID 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. 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - allOf: - - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - 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: session_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: session_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: >- - Pagination cursors for navigating between pages of - results. - - type: object - properties: - data: - type: array - description: The list of records for the current page. - items: - type: object - properties: - object: - type: string - description: Distinguishes the session object. - const: session - id: - type: string - description: The unique ID of the session. - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - impersonator: - type: object - properties: - email: - type: string - description: >- - The email address of the WorkOS Dashboard - user who is impersonating the user. - example: admin@foocorp.com - reason: - type: - - string - - 'null' - description: >- - The justification the impersonator gave for - impersonating the user. - example: >- - Investigating an issue with the customer's - account. - required: - - email - - reason - description: >- - Information about the impersonator if this - session was created via impersonation. - ip_address: - type: - - string - - 'null' - description: >- - The IP address from which the session was - created. - example: 198.51.100.42 - organization_id: - type: string - description: >- - The ID of the organization this session is - associated with. - example: org_01H945H0YD4F97JN9MATX7BYAG - user_agent: - type: - - string - - 'null' - description: >- - The user agent string from the device that - created the session. - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 - user_id: - type: string - description: The ID of the user this session belongs to. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - auth_method: - type: string - enum: - - cross_app_auth - - external_auth - - impersonation - - magic_code - - migrated_session - - oauth - - passkey - - password - - sso - - unknown - description: >- - The authentication method used to create this - session. - example: sso - status: - type: string - enum: - - active - - expired - - revoked - description: The current status of the session. - example: active - expires_at: - format: date-time - type: string - description: The timestamp when the session expires. - example: '2026-01-15T12:00:00.000Z' - ended_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the session ended. - example: null - 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 - - ip_address - - user_agent - - user_id - - auth_method - - status - - expires_at - - ended_at - - created_at - - updated_at - '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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - message: - type: string - description: A human-readable description of the error. - example: Validation failed. - required: - - code - - message - tags: - - user-management.users - /user_management/users/{userId}/api_keys: - get: - operationId: UserApiKeysController_list - summary: List API keys for a user - description: Get a list of API keys owned by a specific user. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - - 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 - tags: - - api_keys - x-feature-flag: user-api-keys - post: - operationId: UserApiKeysController_create - summary: Create an API key for a user - description: >- - Create a new API key owned by a user. The user must have an active - membership in the specified organization. - 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 - tags: - - api_keys - x-feature-flag: user-api-keys - /user_management/users/{userId}/feature-flags: - get: - operationId: UserlandUserFeatureFlagsController_list - summary: List enabled feature flags for a user - description: >- - Get a list of all enabled feature flags for the provided user. This - includes feature flags enabled specifically for the user as well as any - organizations that the user is a member of. - parameters: - - name: userId - required: true - in: path - description: The ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/FlagList' - '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 - tags: - - user-management.users.feature-flags - /user_management/users/{user_id}/authorized_applications: - get: - operationId: AuthorizedApplicationsController_list - summary: List authorized applications - description: Get a list of all Connect applications that the user has authorized. - parameters: - - name: user_id - required: true - in: path - description: The ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizedConnectApplicationList' - '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 - tags: - - user-management.users.authorized-applications - /user_management/users/{user_id}/authorized_applications/{application_id}: - delete: - operationId: AuthorizedApplicationsController_delete - summary: Delete an authorized application - description: Delete an existing Authorized Connect Application. - parameters: - - name: application_id - required: true - in: path - description: The ID or client ID of the application. - schema: - example: conn_app_01HXYZ123456789ABCDEFGHIJ - type: string - - name: user_id - required: true - in: path - description: The ID of the user. - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - 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 - tags: - - user-management.users.authorized-applications - /user_management/users/{user_id}/connected_accounts/{slug}: - get: - operationId: DataIntegrationsUserManagementController_getUserDataInstallation - summary: Get a connected account - description: >- - Retrieves a user's [connected - account](/reference/pipes/connected-account) for a specific provider. - parameters: - - name: user_id - required: true - in: path - description: A [User](/reference/authkit/user) identifier. - schema: - example: user_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: slug - required: true - in: path - description: >- - The slug identifier of the provider (e.g., `github`, `slack`, - `notion`). - schema: - example: github - type: string - - name: organization_id - required: false - in: query - description: >- - An [Organization](/reference/organization) identifier. Optional - parameter if the connection is scoped to an organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - responses: - '200': - description: The connected account was retrieved successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/ConnectedAccount' - '401': - description: The request is missing a valid API key. - '404': - description: The user, organization, or connected account was 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 - tags: - - user-management.data-providers - delete: - operationId: DataIntegrationsUserManagementController_deleteUserDataInstallation - summary: Delete a connected account - description: >- - Disconnects WorkOS's account for the user, including removing any stored - access and refresh tokens. The user will need to reauthorize if they - want to reconnect. This does not revoke access on the provider side. - parameters: - - name: user_id - required: true - in: path - description: A [User](/reference/authkit/user) identifier. - schema: - example: user_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: slug - required: true - in: path - description: >- - The slug identifier of the provider (e.g., `github`, `slack`, - `notion`). - schema: - example: github - type: string - - name: organization_id - required: false - in: query - description: >- - An [Organization](/reference/organization) identifier. Optional - parameter if the connection is scoped to an organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - responses: - '204': - description: The connected account was deleted successfully. - '401': - description: The request is missing a valid API key. - '404': - description: The user, organization, or connected account was 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 - tags: - - user-management.data-providers - /user_management/users/{user_id}/data_providers: - get: - operationId: DataIntegrationsUserManagementController_getUserDataIntegrations - summary: List providers - description: >- - Retrieves a list of available providers and the user's connection status - for each. Returns all providers configured for your environment, along - with the user's [connected account](/reference/pipes/connected-account) - information where applicable. - parameters: - - name: user_id - required: true - in: path - description: >- - A [User](/reference/authkit/user) identifier to list providers and - connected accounts for. - schema: - example: user_01EHZNVPK3SFK441A1RGBFSHRT - type: string - - name: organization_id - required: false - in: query - description: >- - An [Organization](/reference/organization) identifier. Optional - parameter to filter connections for a specific organization. - schema: - example: org_01EHZNVPK3SFK441A1RGBFSHRT - type: string - responses: - '200': - description: The list of data providers was retrieved successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/DataIntegrationsListResponse' - '401': - description: The request is missing a valid API key. - '404': - description: The user or organization was 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 - tags: - - user-management.data-providers - /user_management/users/{userlandUserId}/auth_factors: - post: - operationId: UserlandUserAuthenticationFactorsController_create - summary: Enroll an authentication factor - description: >- - Enrolls a user in a new [authentication - factor](/reference/authkit/mfa/authentication-factor). - parameters: - - name: userlandUserId - required: true - in: path - description: The ID of the [user](/reference/authkit/user). - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/EnrollUserlandUserAuthenticationFactorDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: >- - #/components/schemas/UserlandUserAuthenticationFactorEnrollResponse - '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 - tags: - - user-management.multi-factor-authentication - get: - operationId: UserlandUserAuthenticationFactorsController_list - summary: List authentication factors - description: >- - Lists the [authentication - factors](/reference/authkit/mfa/authentication-factor) for a user. - parameters: - - name: userlandUserId - required: true - in: path - description: The ID of the [user](/reference/authkit/user). - schema: - example: user_01E4ZCR3C56J083X43JQXF3JK5 - type: string - - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserlandUserAuthenticationFactorList' - '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 - tags: - - user-management.multi-factor-authentication - /webhook_endpoints: - get: - operationId: WebhookEndpointsController_list - summary: List Webhook Endpoints - description: Get a list of all of your existing webhook endpoints. - 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: - default: desc - example: desc - enum: - - normal - - desc - - asc - type: string - responses: - '200': - description: List of webhook endpoints. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookEndpointList' - tags: - - webhooks - post: - operationId: WebhookEndpointsController_create - summary: Create a Webhook Endpoint - description: Create a new webhook endpoint to receive event notifications. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateWebhookEndpointDto' - responses: - '201': - description: Webhook endpoint created successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookEndpointJson' - '409': - description: A Webhook Endpoint with the same endpoint URL already exists. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: duplicate_endpoint - const: duplicate_endpoint - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_url - const: invalid_url - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - 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: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - tags: - - webhooks - /webhook_endpoints/{id}: - patch: - operationId: WebhookEndpointsController_update - summary: Update a Webhook Endpoint - description: Update the properties of an existing webhook endpoint. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Webhook Endpoint. - schema: - type: string - example: we_0123456789 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateWebhookEndpointDto' - responses: - '200': - description: Webhook endpoint updated successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/WebhookEndpointJson' - '404': - description: Webhook endpoint not found. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: entity_not_found - const: entity_not_found - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '409': - description: A Webhook Endpoint with the same endpoint URL already exists. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: duplicate_endpoint - const: duplicate_endpoint - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_url - const: invalid_url - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request_parameters - const: invalid_request_parameters - 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: unknown_event_type - message: - type: string - description: >- - A human-readable description of the validation - error. - example: Invalid enum value. - required: - - code - - message - description: The list of validation errors. - required: - - code - - message - - errors - tags: - - webhooks - delete: - operationId: WebhookEndpointsController_delete - summary: Delete a Webhook Endpoint - description: Delete an existing webhook endpoint. - parameters: - - name: id - required: true - in: path - description: Unique identifier of the Webhook Endpoint. - schema: - type: string - example: we_0123456789 - responses: - '204': - description: Webhook endpoint deleted successfully. - '404': - description: Webhook endpoint not found. - content: - application/json: - schema: - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: entity_not_found - const: entity_not_found - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - tags: - - webhooks - /widgets/token: - post: - operationId: WidgetsPublicController_issueWidgetSessionToken - summary: Generate a widget token - description: >- - Generate a widget token scoped to an organization and user with the - specified scopes. - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/WidgetSessionTokenDto' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/WidgetSessionTokenResponse' - '400': - description: Bad Request - content: - application/json: - schema: - oneOf: - - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: >- - Organization not found: - 'org_01EHQMYV6MBK39QC5PZXHY59C3'. - required: - - message - - type: object - properties: - message: - type: array - items: - type: string - description: A list of validation error messages. - example: - - organization_id must be a string - error: - type: string - description: The error type. - example: Bad Request - required: - - message - - error - '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 - tags: - - widgets -info: - title: WorkOS - 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 -tags: - - name: admin-portal - description: Endpoints for the Admin Portal API. - - name: api_keys - description: Manage API keys for environments. - - name: application.client-secrets - description: Manage client secrets for Connect Applications. - - name: applications - description: Manage Connect Applications. - - name: audit-logs - description: Create and query audit log events. - - name: authorization - description: Authorization and access control. - - name: connections - description: Manage SSO connections. - - name: directories - description: Manage directories. - - name: directory-groups - description: Manage directory groups. - - name: directory-users - description: Manage directory users. - - name: events - description: Query events and event streams. - - name: feature-flags - description: Manage feature flags. - - name: feature-flags.targets - description: Manage feature flag targets. - - name: groups - description: Organize and manage user groups within organizations. - - name: multi-factor-auth - description: Multi-factor authentication factor management. - - name: multi-factor-auth.challenges - description: Multi-factor authentication challenge verification. - - name: organization-domains - description: Manage organization domains. - - name: organizations - description: Manage organizations. - - name: organizations.api_keys - description: Manage organization-scoped API keys. - - name: organizations.feature-flags - description: Manage organization-scoped feature flags. - - name: permissions - description: Manage permissions. - - name: pipes - description: Data integration endpoints. - - name: radar - description: Radar fraud detection. - - name: sso - description: Single Sign-On endpoints. - - name: user-management.authentication - description: User authentication endpoints. - - name: user-management.cors-origins - description: Manage CORS origins for user management. - - name: user-management.data-providers - description: Manage data providers. - - name: user-management.invitations - description: Manage user invitations. - - name: user-management.jwt-template - description: Manage JWT templates. - - name: user-management.magic-auth - description: Magic auth endpoints. - - name: user-management.multi-factor-authentication - description: Multi-factor authentication endpoints. - - name: user-management.organization-membership - description: Manage user organization memberships. - - name: user-management.organization-membership.groups - description: Manage groups for a user organization membership. - - name: user-management.redirect-uris - description: Manage redirect URIs. - - name: user-management.session-tokens - description: Session token verification keys. - - name: user-management.users - description: Manage users. - - name: user-management.users.authorized-applications - description: Manage authorized applications for users. - - name: user-management.users.feature-flags - description: Manage user-scoped feature flags. - - name: webhooks - description: Manage webhooks. - - name: widgets - description: Widget endpoints. - - name: workos-connect - description: >- - A unified interface that simplifies authentication and authorization - across customers, partners, and external SaaS tools. -servers: - - url: https://api.workos.com - description: Production - - url: https://api.workos-test.com - description: Staging -components: - 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. - schemas: - UserObject: - type: object - properties: - id: - type: string - description: >- - Your application's user identifier, which will be stored as an - [`external_id`](/authkit/metadata/external-identifiers). Used for - upserting and deduplication. - example: user_12345 - email: - type: string - description: The user's email address. - example: marcelina.davis@example.com - first_name: - type: string - description: The user's first name. - example: Marcelina - last_name: - type: string - description: The user's last name. - example: Davis - metadata: - type: object - description: A set of key-value pairs to attach to the user. - additionalProperties: - type: string - maxLength: 600 - maxProperties: 50 - example: - department: Engineering - role: Developer - propertyNames: - maxLength: 40 - required: - - id - - email - UserConsentOption: - type: object - properties: - claim: - type: string - description: The claim name for this consent option. - example: tos_accepted - type: - type: string - description: The type of consent option. - const: enum - label: - type: string - description: A human-readable label for this consent option. - example: Terms of Service - choices: - type: array - description: The available choices for this consent option. - items: - type: object - properties: - value: - type: string - description: The value of this choice. - example: accepted - label: - type: string - description: A human-readable label for this choice. - example: I accept the Terms of Service - example: - - value: accepted - label: I accept the Terms of Service - required: - - claim - - type - - label - - choices - UserManagementLoginRequest: - type: object - properties: - external_auth_id: - type: string - description: Identifier provided when AuthKit redirected to your login page. - example: ext_auth_01HXYZ123456789ABCDEFGHIJ - user: - description: The user to create or update in AuthKit. - $ref: '#/components/schemas/UserObject' - user_consent_options: - description: >- - Array of [User Consent - Options](/reference/workos-connect/standalone/user-consent-options) - to store with the session. - type: array - items: - $ref: '#/components/schemas/UserConsentOption' - required: - - external_auth_id - - user - ValidateApiKeyDto: - type: object - properties: - value: - type: string - description: The value for an API key. - example: sk_example_1234567890abcdef - required: - - value - RedirectUriDto: - type: object - properties: - uri: - type: string - description: The redirect URI. - example: https://example.com/callback - default: - type: - - boolean - - 'null' - description: Whether this is the default redirect URI. - example: true - required: - - uri - CreateOAuthApplicationDto: - type: object - properties: - name: - type: string - description: The name of the application. - example: My Application - application_type: - type: string - description: The type of application to create. - const: oauth - description: - type: - - string - - 'null' - description: A description for the application. - example: An application for managing user access - scopes: - description: The OAuth scopes granted to the application. - example: &ref_1 - - openid - - profile - - email - type: - - array - - 'null' - items: - type: string - redirect_uris: - description: Redirect URIs for the application. - example: - - uri: https://example.com/callback - default: true - type: - - array - - 'null' - items: - $ref: '#/components/schemas/RedirectUriDto' - uses_pkce: - type: - - boolean - - 'null' - description: Whether the application uses PKCE (Proof Key for Code Exchange). - example: true - is_first_party: - type: boolean - description: >- - Whether this is a first-party application. Third-party applications - require an organization_id. - example: true - organization_id: - type: - - string - - 'null' - description: >- - The organization ID this application belongs to. Required when - is_first_party is false. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - name - - application_type - - is_first_party - CreateM2MApplicationDto: - type: object - properties: - name: - type: string - description: The name of the application. - example: My Application - application_type: - type: string - description: The type of application to create. - const: m2m - description: - type: - - string - - 'null' - description: A description for the application. - example: An application for managing user access - scopes: - description: The OAuth scopes granted to the application. - example: *ref_1 - type: - - array - - 'null' - items: - type: string - organization_id: - type: string - description: The organization ID this application belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - name - - application_type - - organization_id - UpdateOAuthApplicationDto: - type: object - properties: - name: - type: string - description: The name of the application. - example: My Application - description: - type: - - string - - 'null' - description: A description for the application. - example: An application for managing user access - scopes: - description: The OAuth scopes granted to the application. - example: - - openid - - profile - - email - type: - - array - - 'null' - items: - type: string - redirect_uris: - description: Updated redirect URIs for the application. OAuth applications only. - example: - - uri: https://example.com/callback - default: true - type: - - array - - 'null' - items: - $ref: '#/components/schemas/RedirectUriDto' - CreateApplicationSecretDto: - type: object - properties: {} - AuditLogEventActorDto: - type: object - properties: - id: - type: string - description: Actor identifier. - example: user_TF4C5938 - type: - type: string - description: Actor type. - example: user - name: - type: string - description: Optional actor name. - example: Jon Smith - metadata: - type: object - description: Additional data associated with the event or entity. - example: - owner: user_01GBTCQ2 - maxProperties: 50 - additionalProperties: false - patternProperties: &ref_2 - ^[a-zA-Z0-9_-]{0,40}$: - anyOf: - - type: string - maxLength: 500 - - type: number - - type: boolean - required: - - id - - type - AuditLogEventTargetDto: - type: object - properties: - id: - type: string - description: Target identifier. - example: user_TF4C5938 - type: - type: string - description: Target type. - example: user - name: - type: string - description: Optional target name. - example: Jon Smith - metadata: - type: object - description: Additional data associated with the event or entity. - example: - owner: user_01GBTCQ2 - maxProperties: 50 - additionalProperties: false - patternProperties: *ref_2 - required: - - id - - type - AuditLogEventContextDto: - type: object - properties: - location: - type: string - description: IP Address or some other geolocation identifier. - example: 123.123.123.123 - user_agent: - type: string - description: User agent string. - example: Chrome/104.0.0.0 - required: - - location - AuditLogEventDto: - type: object - properties: - action: - type: string - description: Identifier of what happened. - example: user.signed_in - occurred_at: - type: string - description: ISO-8601 value of when the action occurred. - example: '2026-02-02T16:35:39.317Z' - format: date-time - actor: - description: The entity that performed the action. - $ref: '#/components/schemas/AuditLogEventActorDto' - targets: - description: The resources affected by the action. - type: array - items: - $ref: '#/components/schemas/AuditLogEventTargetDto' - context: - description: Additional context about where and how the action occurred. - $ref: '#/components/schemas/AuditLogEventContextDto' - metadata: - type: object - description: Additional data associated with the event or entity. - example: - owner: user_01GBTCQ2 - maxProperties: 50 - additionalProperties: false - patternProperties: *ref_2 - version: - type: integer - description: What schema version the event is associated with. - example: 1 - required: - - action - - occurred_at - - actor - - targets - - context - AuditLogEventIngestionDto: - type: object - properties: - organization_id: - type: string - description: The unique ID of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - event: - description: The audit log event to create. - $ref: '#/components/schemas/AuditLogEventDto' - required: - - organization_id - - event - AuditLogExportCreationDto: - type: object - properties: - organization_id: - type: string - description: The unique ID of the Organization. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - range_start: - type: string - description: ISO-8601 value for start of the export range. - example: '2022-07-02T18:09:06.996Z' - range_end: - type: string - description: ISO-8601 value for end of the export range. - example: '2022-09-02T18:09:06.996Z' - actions: - description: List of actions to filter against. - example: - - user.signed_in - type: array - items: - type: string - actors: - description: Deprecated. Use `actor_names` instead. - deprecated: true - example: - - Jon Smith - type: array - items: - type: string - actor_names: - description: List of actor names to filter against. - example: - - Jon Smith - type: array - items: - type: string - actor_ids: - description: List of actor IDs to filter against. - example: - - user_01GBZK5MP7TD1YCFQHFR22180V - type: array - items: - type: string - targets: - description: List of target types to filter against. - example: - - team - type: array - items: - type: string - required: - - organization_id - - range_start - - range_end - UpdateAuditLogsRetentionDto: - type: object - properties: - retention_period_in_days: - type: integer - description: >- - The number of days Audit Log events will be retained. Valid values - are `30` and `365`. - example: 30 - required: - - retention_period_in_days - AuditLogSchemaActorDto: - type: object - properties: - metadata: - type: object - description: JSON schema for actor metadata. - example: - type: object - properties: - role: - type: string - required: - - metadata - AuditLogSchemaTargetDto: - type: object - properties: - type: - type: string - description: The type of the target resource. - example: invoice - metadata: - type: object - description: Optional JSON schema for target metadata. - example: - type: object - properties: - cost: - type: number - required: - - type - AuditLogSchemaDto: - type: object - properties: - actor: - description: The metadata schema for the actor. - $ref: '#/components/schemas/AuditLogSchemaActorDto' - targets: - description: The list of targets for the schema. - type: array - items: - $ref: '#/components/schemas/AuditLogSchemaTargetDto' - metadata: - type: object - description: Optional JSON schema for event metadata. - example: - type: object - properties: - transactionId: - type: string - required: - - targets - ChallengeAuthenticationFactorDto: - type: object - properties: - sms_template: - type: string - description: >- - A custom template for the SMS message. Use the {{code}} placeholder - to include the verification code. - example: Your verification code is {{code}}. - CheckAuthorizationDto: - allOf: - - type: object - properties: - permission_slug: - type: string - description: The slug of the permission to check. - example: posts:create - required: - - permission_slug - - oneOf: - - type: object - properties: - resource_id: - type: string - description: >- - The ID of the resource. Mutually exclusive with - `resource_external_id` and `resource_type_slug`. - example: resource_01HXYZ123456789ABCDEFGHIJ - required: - - resource_id - not: - anyOf: - - properties: - resource_external_id: - x-exclude-from-lint: true - required: - - resource_external_id - - properties: - resource_type_slug: - x-exclude-from-lint: true - required: - - resource_type_slug - - type: object - properties: - resource_external_id: - type: string - description: >- - The external ID of the resource. Required with - `resource_type_slug`. Mutually exclusive with `resource_id`. - example: my-custom-id - resource_type_slug: - type: string - description: >- - The slug of the resource type. Required with - `resource_external_id`. Mutually exclusive with - `resource_id`. - example: document - required: - - resource_external_id - - resource_type_slug - not: - anyOf: - - properties: - resource_id: - x-exclude-from-lint: true - required: - - resource_id - x-mutually-exclusive-body-groups: *ref_3 - AssignRoleDto: - allOf: - - type: object - properties: - role_slug: - type: string - description: The slug of the role to assign. - example: editor - required: - - role_slug - - oneOf: - - type: object - properties: - resource_id: - type: string - description: >- - The ID of the resource. Mutually exclusive with - `resource_external_id` and `resource_type_slug`. - example: authz_resource_01HXYZ123456789ABCDEFGH - required: - - resource_id - not: - anyOf: - - properties: - resource_external_id: - x-exclude-from-lint: true - required: - - resource_external_id - - properties: - resource_type_slug: - x-exclude-from-lint: true - required: - - resource_type_slug - - type: object - properties: - resource_external_id: - type: string - description: >- - The external ID of the resource. Required with - `resource_type_slug`. Mutually exclusive with `resource_id`. - example: project-ext-456 - resource_type_slug: - type: string - description: >- - The resource type slug. Required with - `resource_external_id`. Mutually exclusive with - `resource_id`. - example: project - required: - - resource_external_id - - resource_type_slug - not: - anyOf: - - properties: - resource_id: - x-exclude-from-lint: true - required: - - resource_id - x-mutually-exclusive-body-groups: *ref_4 - RemoveRoleDto: - allOf: - - type: object - properties: - role_slug: - type: string - description: The slug of the role to remove. - example: editor - required: - - role_slug - - oneOf: - - type: object - properties: - resource_id: - type: string - description: >- - The ID of the resource. Mutually exclusive with - `resource_external_id` and `resource_type_slug`. - example: authz_resource_01HXYZ123456789ABCDEFGH - required: - - resource_id - not: - anyOf: - - properties: - resource_external_id: - x-exclude-from-lint: true - required: - - resource_external_id - - properties: - resource_type_slug: - x-exclude-from-lint: true - required: - - resource_type_slug - - type: object - properties: - resource_external_id: - type: string - description: >- - The external ID of the resource. Required with - `resource_type_slug`. Mutually exclusive with `resource_id`. - example: external_01HXYZ123456789ABCDEFGH - resource_type_slug: - type: string - description: >- - The resource type slug. Required with - `resource_external_id`. Mutually exclusive with - `resource_id`. - example: project - required: - - resource_external_id - - resource_type_slug - not: - anyOf: - - properties: - resource_id: - x-exclude-from-lint: true - required: - - resource_id - x-mutually-exclusive-body-groups: *ref_5 - SetRolePermissionsDto: - type: object - properties: - permissions: - description: The permission slugs to assign to the role. - example: - - billing:read - - billing:write - - invoices:manage - - reports:view - type: array - items: - type: string - required: - - permissions - AddRolePermissionDto: - type: object - properties: - slug: - type: string - description: The slug of the permission to add to the role. - example: reports:export - required: - - slug - CreateOrganizationRoleDto: - type: object - properties: - slug: - type: string - maxLength: 48 - description: >- - A unique identifier for the role within the organization. When - provided, must begin with 'org-' and contain only lowercase letters, - numbers, hyphens, and underscores. When omitted, a slug is - auto-generated from the role name and a random suffix. - example: org-billing-admin - name: - type: string - maxLength: 48 - description: A descriptive name for the role. - example: Billing Administrator - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role's purpose. - example: Can manage billing and invoices - resource_type_slug: - type: string - maxLength: 48 - description: The slug of the resource type the role is scoped to. - example: organization - required: - - name - UpdateOrganizationRoleDto: - type: object - properties: - name: - type: string - maxLength: 48 - description: A descriptive name for the role. - example: Finance Administrator - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role's purpose. - example: Can manage all financial operations - CreateAuthorizationPermissionDto: - type: object - properties: - slug: - type: string - maxLength: 48 - description: >- - A unique key to reference the permission. Must be lowercase and - contain only letters, numbers, hyphens, underscores, colons, - periods, and asterisks. - example: documents:read - name: - type: string - maxLength: 48 - description: A descriptive name for the Permission. - example: View Documents - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the Permission. - example: Allows viewing document contents - resource_type_slug: - type: string - maxLength: 48 - description: The slug of the resource type this permission is scoped to. - example: document - required: - - slug - - name - UpdateAuthorizationPermissionDto: - type: object - properties: - name: - type: string - maxLength: 48 - description: A descriptive name for the Permission. - example: View Documents - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the Permission. - example: Allows viewing document contents - CreateRoleDto: - type: object - properties: - slug: - type: string - maxLength: 48 - description: A unique slug for the role. - example: editor - name: - type: string - maxLength: 48 - description: A descriptive name for the role. - example: Editor - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role. - example: Can edit resources - resource_type_slug: - type: string - maxLength: 48 - description: The slug of the resource type the role is scoped to. - example: organization - required: - - slug - - name - UpdateRoleDto: - type: object - properties: - name: - type: string - maxLength: 48 - description: A descriptive name for the role. - example: Super Administrator - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the role. - example: Full administrative access to all resources - UpdateAuthorizationResourceDto: - allOf: - - type: object - properties: - name: - type: string - maxLength: 48 - description: A display name for the resource. - example: Updated Name - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the resource. - example: Updated description - - oneOf: - - type: object - not: - anyOf: - - properties: - parent_resource_id: - x-exclude-from-lint: true - required: - - parent_resource_id - - properties: - parent_resource_external_id: - x-exclude-from-lint: true - required: - - parent_resource_external_id - - properties: - parent_resource_type_slug: - x-exclude-from-lint: true - required: - - parent_resource_type_slug - - type: object - properties: - parent_resource_id: - type: string - description: >- - The ID of the parent resource. Mutually exclusive with - `parent_resource_external_id` and - `parent_resource_type_slug`. - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - required: - - parent_resource_id - not: - anyOf: - - properties: - parent_resource_external_id: - x-exclude-from-lint: true - required: - - parent_resource_external_id - - properties: - parent_resource_type_slug: - x-exclude-from-lint: true - required: - - parent_resource_type_slug - - type: object - properties: - parent_resource_external_id: - type: string - description: >- - The external ID of the parent resource. Required with - `parent_resource_type_slug`. Mutually exclusive with - `parent_resource_id`. - example: parent-workspace-01 - parent_resource_type_slug: - type: string - description: >- - The resource type slug of the parent resource. Required with - `parent_resource_external_id`. Mutually exclusive with - `parent_resource_id`. - example: workspace - required: - - parent_resource_external_id - - parent_resource_type_slug - not: - anyOf: - - properties: - parent_resource_id: - x-exclude-from-lint: true - required: - - parent_resource_id - x-mutually-exclusive-body-groups: *ref_0 - CreateAuthorizationResourceDto: - allOf: - - type: object - properties: - external_id: - type: string - maxLength: 128 - description: An external identifier for the resource. - example: my-workspace-01 - name: - type: string - maxLength: 48 - description: A display name for the resource. - example: Acme Workspace - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the resource. - example: Primary workspace for the Acme team - resource_type_slug: - type: string - description: The slug of the resource type. - example: workspace - organization_id: - type: string - description: The ID of the organization this resource belongs to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - required: - - external_id - - name - - resource_type_slug - - organization_id - - oneOf: - - type: object - not: - anyOf: - - properties: - parent_resource_id: - x-exclude-from-lint: true - required: - - parent_resource_id - - properties: - parent_resource_external_id: - x-exclude-from-lint: true - required: - - parent_resource_external_id - - properties: - parent_resource_type_slug: - x-exclude-from-lint: true - required: - - parent_resource_type_slug - - type: object - properties: - parent_resource_id: - type: - - string - - 'null' - description: >- - The ID of the parent resource. Mutually exclusive with - `parent_resource_external_id` and - `parent_resource_type_slug`. - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - required: - - parent_resource_id - not: - anyOf: - - properties: - parent_resource_external_id: - x-exclude-from-lint: true - required: - - parent_resource_external_id - - properties: - parent_resource_type_slug: - x-exclude-from-lint: true - required: - - parent_resource_type_slug - - type: object - properties: - parent_resource_external_id: - type: string - description: >- - The external ID of the parent resource. Required with - `parent_resource_type_slug`. Mutually exclusive with - `parent_resource_id`. - example: parent-workspace-01 - parent_resource_type_slug: - type: string - description: >- - The resource type slug of the parent resource. Required with - `parent_resource_external_id`. Mutually exclusive with - `parent_resource_id`. - example: workspace - required: - - parent_resource_external_id - - parent_resource_type_slug - not: - anyOf: - - properties: - parent_resource_id: - x-exclude-from-lint: true - required: - - parent_resource_id - x-mutually-exclusive-body-groups: *ref_6 - CreateCorsOriginDto: - type: object - properties: - origin: - type: string - description: The origin URL to allow for CORS requests. - example: https://example.com - required: - - origin - CreateGroupMembershipDto: - type: object - properties: - organization_membership_id: - type: string - description: The ID of the Organization Membership to add to the group. - example: om_01HXYZ123456789ABCDEFGHIJ - required: - - organization_membership_id - CreateGroupDto: - type: object - properties: - name: - type: string - maxLength: 256 - description: The name of the Group. - example: Engineering - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the Group. - example: The engineering team - required: - - name - UpdateGroupDto: - type: object - properties: - name: - type: string - maxLength: 256 - description: The name of the Group. - example: Engineering - description: - type: - - string - - 'null' - maxLength: 150 - description: An optional description of the Group. - example: The engineering team - UpdateJwtTemplateDto: - type: object - properties: - content: - type: string - description: The JWT template content as a Liquid template string. - example: >- - {"urn:myapp:full_name": "{{user.first_name}} {{user.last_name}}", - "urn:myapp:email": "{{user.email}}"} - required: - - content - CreateOrganizationDomainDto: - type: object - properties: - domain: - type: string - description: The domain to add to the organization. - example: foo-corp.com - organization_id: - type: string - description: The ID of the organization to add the domain to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - required: - - domain - - organization_id - CreateOrganizationApiKeyDto: - type: object - properties: - name: - type: string - description: The name for the API key. - example: Production API Key - permissions: - description: The permission slugs to assign to the API key. - example: - - posts:read - - posts:write - type: array - items: - type: string - required: - - name - OrganizationDomainDataDto: - type: object - properties: - domain: - type: string - description: The domain value. - example: foo-corp.com - state: - type: string - enum: - - pending - - verified - description: The verification state of the domain. - example: verified - required: - - domain - - state - OrganizationDto: - type: object - properties: - name: - type: string - description: The name of the organization. - example: Foo Corp - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the organization allows profiles from outside the - organization to sign in. - example: false - domains: - description: >- - The domains associated with the organization. Deprecated in favor of - `domain_data`. - example: - - example.com - type: array - items: - type: string - domain_data: - description: >- - The domains associated with the organization, including verification - state. - type: array - items: - $ref: '#/components/schemas/OrganizationDomainDataDto' - metadata: - type: - - object - - 'null' - additionalProperties: &ref_7 - type: string - maxLength: 600 - maxProperties: 50 - example: &ref_8 - tier: diamond - description: >- - Object containing [metadata](/authkit/metadata) key/value pairs - associated with the Organization. - propertyNames: - maxLength: 40 - external_id: - type: - - string - - 'null' - maxLength: 128 - example: ext_12345 - description: An external identifier for the Organization. - required: - - name - UpdateOrganizationDto: - type: object - properties: - name: - type: string - description: The name of the organization. - example: Foo Corp - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the organization allows profiles from outside the - organization to sign in. - example: false - domains: - description: >- - The domains associated with the organization. Deprecated in favor of - `domain_data`. - example: - - foo-corp.com - deprecated: true - type: array - items: - type: string - domain_data: - description: >- - The domains associated with the organization, including verification - state. - type: array - items: - $ref: '#/components/schemas/OrganizationDomainDataDto' - stripe_customer_id: - type: string - description: The Stripe customer ID associated with the organization. - example: cus_R9qWAGMQ6nGE7V - metadata: - type: - - object - - 'null' - additionalProperties: *ref_7 - maxProperties: 50 - example: *ref_8 - description: >- - Object containing [metadata](/authkit/metadata) key/value pairs - associated with the Organization. - propertyNames: - maxLength: 40 - external_id: - type: - - string - - 'null' - maxLength: 128 - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - description: An external identifier for the Organization. - SsoIntentOptions: - type: object - properties: - bookmark_slug: - type: string - description: The bookmark slug to use for SSO. - example: chatgpt - provider_type: - type: string - description: The SSO provider type to configure. - example: GoogleSAML - const: GoogleSAML - DomainVerificationIntentOptions: - type: object - properties: - domain_name: - type: string - description: >- - The domain name to verify. When provided, the domain verification - flow will skip the domain entry form and go directly to the - verification step. - example: example.com - IntentOptions: - type: object - properties: - sso: - description: SSO-specific options for the Admin Portal. - $ref: '#/components/schemas/SsoIntentOptions' - domain_verification: - description: Domain verification-specific options for the Admin Portal. - $ref: '#/components/schemas/DomainVerificationIntentOptions' - GenerateLinkDto: - type: object - properties: - return_url: - type: string - description: >- - The URL to go to when an admin clicks on your logo in the Admin - Portal. If not specified, the return URL configured on the - [Redirects](https://dashboard.workos.com/redirects) page will be - used. - example: https://example.com/admin-portal/return - success_url: - type: string - description: >- - The URL to redirect the admin to when they finish setup. If not - specified, the success URL configured on the - [Redirects](https://dashboard.workos.com/redirects) page will be - used. - example: https://example.com/admin-portal/success - organization: - type: string - description: An [Organization](/reference/organization) identifier. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - intent: - type: string - description: |2- - - The intent of the Admin Portal. - - `sso` - Launch Admin Portal for creating SSO connections - - `dsync` - Launch Admin Portal for creating Directory Sync connections - - `audit_logs` - Launch Admin Portal for viewing Audit Logs - - `log_streams` - Launch Admin Portal for creating Log Streams - - `domain_verification` - Launch Admin Portal for Domain Verification - - `certificate_renewal` - Launch Admin Portal for renewing SAML Certificates - - `bring_your_own_key` - Launch Admin Portal for configuring Bring Your Own Key - example: sso - enum: - - sso - - dsync - - audit_logs - - log_streams - - domain_verification - - certificate_renewal - - bring_your_own_key - intent_options: - description: Options to configure the Admin Portal based on the intent. - $ref: '#/components/schemas/IntentOptions' - it_contact_emails: - description: >- - The email addresses of the IT contacts to grant access to the Admin - Portal for the given organization. Accepts up to 20 emails. - example: - - it-contact@example.com - maxItems: 20 - items: - type: string - type: array - required: - - organization - CreateRedirectUriDto: - type: object - properties: - uri: - type: string - description: The redirect URI to create. - example: https://example.com/callback - required: - - uri - EnrollUserlandUserAuthenticationFactorDto: - type: object - properties: - type: - type: string - description: The type of the factor to enroll. - example: totp - const: totp - totp_issuer: - type: string - description: >- - Your application or company name displayed in the user's - authenticator app. - example: WorkOS - totp_user: - type: string - description: The user's account name displayed in their authenticator app. - example: user@example.com - totp_secret: - type: string - description: >- - The Base32-encoded shared secret for TOTP factors. This can be - provided when creating the auth factor, otherwise it will be - generated. The algorithm used to derive TOTP codes is SHA-1, the - code length is 6 digits, and the timestep is 30 seconds – the secret - must be compatible with these parameters. - example: JBSWY3DPEHPK3PXP - required: - - type - CreateUserlandMagicCodeAndReturnDto: - type: object - properties: - email: - type: string - description: The email address to send the magic code to. - example: marcelina.davis@example.com - invitation_token: - type: string - description: The invitation token to associate with this magic code. - example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 - required: - - email - CreateUserlandUserInviteOptionsDto: - type: object - properties: - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - organization_id: - type: string - description: >- - The ID of the [organization](/reference/organization) that the - recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - role_slug: - type: string - description: >- - The [role](/authkit/roles) that the recipient will receive when they - join the organization in the invitation. - example: admin - expires_in_days: - type: integer - description: >- - How many days the invitations will be valid for. Must be between 1 - and 30 days. Defaults to 7 days if not specified. - example: 7 - inviter_user_id: - type: string - description: >- - The ID of the [user](/reference/authkit/user) who invites the - recipient. The invitation email will mention the name of this user. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - locale: - type: string - enum: - - af - - am - - ar - - bg - - bn - - bs - - ca - - cs - - da - - de - - de-DE - - el - - en - - en-AU - - en-CA - - en-GB - - en-US - - es - - es-419 - - es-ES - - es-US - - et - - fa - - fi - - fil - - fr - - fr-BE - - fr-CA - - fr-FR - - fy - - gl - - gu - - ha - - he - - hi - - hr - - hu - - hy - - id - - is - - it - - it-IT - - ja - - jv - - ka - - kk - - km - - kn - - ko - - lt - - lv - - mk - - ml - - mn - - mr - - ms - - my - - nb - - ne - - nl - - nl-BE - - nl-NL - - nn - - 'no' - - pa - - pl - - pt - - pt-BR - - pt-PT - - ro - - ru - - sk - - sl - - sq - - sr - - sv - - sw - - ta - - te - - th - - tr - - uk - - ur - - uz - - vi - - zh - - zh-CN - - zh-HK - - zh-TW - - zu - description: >- - The locale to use when rendering the invitation email. See - [supported locales](/authkit/hosted-ui/localization). - example: en - required: - - email - ResendUserlandUserInviteOptionsDto: - type: object - properties: - locale: - type: string - enum: - - af - - am - - ar - - bg - - bn - - bs - - ca - - cs - - da - - de - - de-DE - - el - - en - - en-AU - - en-CA - - en-GB - - en-US - - es - - es-419 - - es-ES - - es-US - - et - - fa - - fi - - fil - - fr - - fr-BE - - fr-CA - - fr-FR - - fy - - gl - - gu - - ha - - he - - hi - - hr - - hu - - hy - - id - - is - - it - - it-IT - - ja - - jv - - ka - - kk - - km - - kn - - ko - - lt - - lv - - mk - - ml - - mn - - mr - - ms - - my - - nb - - ne - - nl - - nl-BE - - nl-NL - - nn - - 'no' - - pa - - pl - - pt - - pt-BR - - pt-PT - - ro - - ru - - sk - - sl - - sq - - sr - - sv - - sw - - ta - - te - - th - - tr - - uk - - ur - - uz - - vi - - zh - - zh-CN - - zh-HK - - zh-TW - - zu - description: >- - The locale to use when rendering the invitation email. See - [supported locales](/authkit/hosted-ui/localization). - example: en - CreateUserlandUserOrganizationMembershipDto: - allOf: - - type: object - properties: - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E - organization_id: - type: string - description: >- - The ID of the [organization](/reference/organization) which the - user belongs to. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - required: - - user_id - - organization_id - - oneOf: - - type: object - not: - anyOf: - - properties: - role_slug: - x-exclude-from-lint: true - required: - - role_slug - - properties: - role_slugs: - x-exclude-from-lint: true - required: - - role_slugs - - type: object - properties: - role_slug: - type: string - description: >- - A single role identifier. Defaults to `member` or the - explicit default role. Mutually exclusive with `role_slugs`. - example: admin - required: - - role_slug - not: - anyOf: - - properties: - role_slugs: - x-exclude-from-lint: true - required: - - role_slugs - - type: object - properties: - role_slugs: - description: >- - An array of role identifiers. Limited to one role when - Multiple Roles is disabled. Mutually exclusive with - `role_slug`. - example: - - admin - type: array - items: - type: string - required: - - role_slugs - not: - anyOf: - - properties: - role_slug: - x-exclude-from-lint: true - required: - - role_slug - x-mutually-exclusive-body-groups: *ref_9 - UpdateUserlandUserOrganizationMembershipDto: - x-mutually-exclusive-body-groups: *ref_10 - oneOf: - - type: object - not: - anyOf: - - properties: - role_slug: - x-exclude-from-lint: true - required: - - role_slug - - properties: - role_slugs: - x-exclude-from-lint: true - required: - - role_slugs - - type: object - properties: - role_slug: - type: string - description: >- - A single role identifier. Defaults to `member` or the explicit - default role. Mutually exclusive with `role_slugs`. - example: admin - required: - - role_slug - not: - anyOf: - - properties: - role_slugs: - x-exclude-from-lint: true - required: - - role_slugs - - type: object - properties: - role_slugs: - description: >- - An array of role identifiers. Limited to one role when Multiple - Roles is disabled. Mutually exclusive with `role_slug`. - example: - - admin - type: array - items: - type: string - required: - - role_slugs - not: - anyOf: - - properties: - role_slug: - x-exclude-from-lint: true - required: - - role_slug - 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 - CreateUserlandUserDto: - allOf: - - type: object - properties: - email: - type: string - 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 - email_verified: - type: - - boolean - - 'null' - description: Whether the user's email has been verified. - example: true - metadata: - type: - - object - - 'null' - additionalProperties: *ref_7 - maxProperties: 50 - example: &ref_12 - timezone: America/New_York - description: >- - Object containing metadata key/value pairs associated with the - user. - propertyNames: - maxLength: 40 - external_id: - type: - - string - - 'null' - maxLength: 128 - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - required: - - email - - oneOf: - - type: object - not: - anyOf: - - properties: - password: - x-exclude-from-lint: true - required: - - password - - properties: - password_hash: - x-exclude-from-lint: true - required: - - password_hash - - properties: - password_hash_type: - x-exclude-from-lint: true - required: - - password_hash_type - - type: object - properties: - password: - type: - - string - - 'null' - description: >- - The password to set for the user. Mutually exclusive with - `password_hash` and `password_hash_type`. - example: strong_password_123! - required: - - password - not: - anyOf: - - properties: - password_hash: - x-exclude-from-lint: true - required: - - password_hash - - properties: - password_hash_type: - x-exclude-from-lint: true - required: - - password_hash_type - - type: object - properties: - password_hash: - type: string - description: >- - The hashed password to set for the user. Required with - `password_hash_type`. Mutually exclusive with `password`. - example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy - password_hash_type: - type: string - enum: &ref_13 - - bcrypt - - firebase-scrypt - - ssha - - scrypt - - pbkdf2 - - argon2 - description: >- - The algorithm originally used to hash the password, used - when providing a `password_hash`. Required with - `password_hash`. Mutually exclusive with `password`. - example: bcrypt - required: - - password_hash - - password_hash_type - not: - anyOf: - - properties: - password: - x-exclude-from-lint: true - required: - - password - x-mutually-exclusive-body-groups: *ref_11 - UpdateUserlandUserDto: - allOf: - - type: object - properties: - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - first_name: - type: string - description: The first name of the user. - example: Marcelina - last_name: - type: string - description: The last name of the user. - example: Davis - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - metadata: - type: - - object - - 'null' - additionalProperties: *ref_7 - maxProperties: 50 - example: *ref_12 - description: >- - Object containing metadata key/value pairs associated with the - user. - propertyNames: - maxLength: 40 - external_id: - type: - - string - - 'null' - maxLength: 128 - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - - oneOf: - - type: object - not: - anyOf: - - properties: - password: - x-exclude-from-lint: true - required: - - password - - properties: - password_hash: - x-exclude-from-lint: true - required: - - password_hash - - properties: - password_hash_type: - x-exclude-from-lint: true - required: - - password_hash_type - - type: object - properties: - password: - type: string - description: >- - The password to set for the user. Mutually exclusive with - `password_hash` and `password_hash_type`. - example: strong_password_123! - required: - - password - not: - anyOf: - - properties: - password_hash: - x-exclude-from-lint: true - required: - - password_hash - - properties: - password_hash_type: - x-exclude-from-lint: true - required: - - password_hash_type - - type: object - properties: - password_hash: - type: string - description: >- - The hashed password to set for the user. Required with - `password_hash_type`. Mutually exclusive with `password`. - example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy - password_hash_type: - type: string - enum: *ref_13 - description: >- - The algorithm originally used to hash the password, used - when providing a `password_hash`. Required with - `password_hash`. Mutually exclusive with `password`. - example: bcrypt - required: - - password_hash - - password_hash_type - not: - anyOf: - - properties: - password: - x-exclude-from-lint: true - required: - - password - x-mutually-exclusive-body-groups: *ref_14 - VerifyEmailAddressDto: - type: object - properties: - code: - type: string - description: The one-time email verification code. - example: '123456' - required: - - code - CreatePasswordResetTokenDto: - type: object - properties: - email: - type: string - description: The email address of the user requesting a password reset. - example: marcelina.davis@example.com - required: - - email - CreatePasswordResetDto: - type: object - properties: - token: - type: string - description: The password reset token. - example: Z1Y2X3W4V5U6T7S8R9Q0P1O2N3 - new_password: - type: string - description: The new password to set for the user. - example: strong_password_123! - required: - - token - - new_password - SendEmailChangeDto: - type: object - properties: - new_email: - type: string - description: The new email address to change to. - example: new.email@example.com - required: - - new_email - ConfirmEmailChangeDto: - type: object - properties: - code: - type: string - description: The one-time code used to confirm the email change. - example: '123456' - required: - - code - UserlandRevokeSessionDto: - type: object - properties: - session_id: - type: string - description: >- - The ID of the session to revoke. This can be extracted from the - `sid` claim of the access token. - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - return_to: - type: string - description: The URL to redirect the user to after session revocation. - example: https://example.com - required: - - session_id - CreateWebhookEndpointDto: - type: object - properties: - endpoint_url: - type: string - description: The HTTPS URL where webhooks will be sent. - example: https://example.com/webhooks - events: - type: array - description: The events that the Webhook Endpoint is subscribed to. - items: - type: string - enum: &ref_15 - - authentication.email_verification_succeeded - - authentication.magic_auth_failed - - authentication.magic_auth_succeeded - - authentication.mfa_succeeded - - authentication.oauth_failed - - authentication.oauth_succeeded - - authentication.password_failed - - authentication.password_succeeded - - authentication.passkey_failed - - authentication.passkey_succeeded - - authentication.sso_failed - - authentication.sso_started - - authentication.sso_succeeded - - authentication.sso_timed_out - - authentication.radar_risk_detected - - api_key.created - - api_key.revoked - - connection.activated - - connection.deactivated - - connection.saml_certificate_renewal_required - - connection.saml_certificate_renewed - - connection.deleted - - dsync.activated - - dsync.deleted - - dsync.group.created - - dsync.group.deleted - - dsync.group.updated - - dsync.group.user_added - - dsync.group.user_removed - - dsync.user.created - - dsync.user.deleted - - dsync.user.updated - - email_verification.created - - group.created - - group.deleted - - group.member_added - - group.member_removed - - group.updated - - flag.created - - flag.deleted - - flag.updated - - flag.rule_updated - - invitation.accepted - - invitation.created - - invitation.resent - - invitation.revoked - - magic_auth.created - - organization.created - - organization.deleted - - organization.updated - - organization_domain.created - - organization_domain.deleted - - organization_domain.updated - - organization_domain.verified - - organization_domain.verification_failed - - password_reset.created - - password_reset.succeeded - - user.created - - user.updated - - user.deleted - - organization_membership.created - - organization_membership.deleted - - organization_membership.updated - - role.created - - role.deleted - - role.updated - - organization_role.created - - organization_role.deleted - - organization_role.updated - - permission.created - - permission.deleted - - permission.updated - - session.created - - session.revoked - - waitlist_user.approved - - waitlist_user.created - - waitlist_user.denied - example: - - user.created - - dsync.user.created - required: - - endpoint_url - - events - UpdateWebhookEndpointDto: - type: object - properties: - endpoint_url: - type: string - description: The HTTPS URL where webhooks will be sent. - example: https://example.com/webhooks - status: - type: string - enum: - - enabled - - disabled - description: Whether the Webhook Endpoint is enabled or disabled. - example: enabled - events: - type: array - description: The events that the Webhook Endpoint is subscribed to. - items: - type: string - enum: *ref_15 - example: - - user.created - - dsync.user.created - WidgetSessionTokenDto: - type: object - properties: - organization_id: - type: string - description: The ID of the organization to scope the widget session to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - user_id: - type: string - description: The ID of the user to issue the widget session token for. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - scopes: - type: array - description: The scopes to grant the widget session. - items: - type: string - enum: - - widgets:users-table:manage - - widgets:domain-verification:manage - - widgets:sso:manage - - widgets:api-keys:manage - - widgets:dsync:manage - - widgets:audit-log-streaming:manage - example: - - widgets:users-table:manage - required: - - organization_id - TokenQueryDto: - type: object - properties: - client_id: - type: string - description: The client ID of the WorkOS environment. - example: client_01HZBC6N1EB1ZY7KG32X - client_secret: - type: string - description: The client secret of the WorkOS environment. - example: sk_example_123456789 - code: - type: string - description: The authorization code received from the authorization callback. - example: authorization_code_value - grant_type: - type: string - description: The grant type for the token request. - example: authorization_code - const: authorization_code - required: - - client_id - - client_secret - - code - - grant_type - ExternalAuthCompleteResponse: - type: object - properties: - redirect_uri: - type: string - description: URI to redirect the user back to AuthKit to complete the OAuth flow. - example: >- - https://your-authkit-domain.workos.com/oauth/authorize/complete?state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdGF0ZSI6InJhbmRvbV9zdGF0ZV9zdHJpbmciLCJpYXQiOjE3NDI2MDQ4NTN9.abc123def456ghi789 - required: - - redirect_uri - 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 - ApiKeyValidationResponse: - type: object - properties: - api_key: - oneOf: - - $ref: '#/components/schemas/ApiKey' - - type: 'null' - required: - - api_key - ConnectApplication: - allOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connect application object. - example: connect_application - const: connect_application - id: - type: string - description: The unique ID of the connect application. - example: conn_app_01HXYZ123456789ABCDEFGHIJ - client_id: - type: string - description: The client ID of the connect application. - example: client_01HXYZ123456789ABCDEFGHIJ - description: - type: - - string - - 'null' - description: A description of the connect application. - example: An application for managing user access - name: - type: string - description: The name of the connect application. - example: My Application - scopes: - type: array - items: - type: string - description: The scopes available for this application. - example: - - openid - - profile - - email - 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 - - client_id - - description - - name - - scopes - - created_at - - updated_at - - oneOf: - - allOf: - - type: object - properties: - application_type: - type: string - description: The type of the application. - const: oauth - redirect_uris: - type: array - items: - type: object - properties: - uri: - type: string - format: uri - description: The redirect URI for the application. - example: https://example.com/callback - default: - type: boolean - description: Whether this is the default redirect URI. - example: true - required: - - uri - - default - description: The redirect URIs configured for this application. - uses_pkce: - type: boolean - description: Whether the application uses PKCE for authorization. - example: true - required: - - application_type - - redirect_uris - - uses_pkce - - oneOf: - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: true - const: true - required: - - is_first_party - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: Whether the application was dynamically registered. - example: false - const: false - organization_id: - type: string - description: >- - The ID of the organization the application belongs - to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - is_first_party - - was_dynamically_registered - - organization_id - - type: object - properties: - is_first_party: - type: boolean - description: >- - Whether the application is a first-party - application. - example: false - const: false - was_dynamically_registered: - type: boolean - description: Whether the application was dynamically registered. - example: true - const: true - required: - - is_first_party - - was_dynamically_registered - - type: object - properties: - application_type: - type: string - description: The type of the application. - example: m2m - const: m2m - organization_id: - type: string - description: The ID of the organization the application belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - application_type - - organization_id - ConnectApplicationList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/ConnectApplication' - 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: conn_app_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: conn_app_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - AuthorizedConnectApplicationList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the authorized connect application object. - const: authorized_connect_application - id: - type: string - description: The unique ID of the authorized connect application. - example: authorized_connect_app_01HXYZ123456789ABCDEFGHIJ - granted_scopes: - type: array - items: - type: string - description: The scopes granted by the user to the application. - example: - - openid - - profile - - email - oauth_resource: - type: string - description: >- - The OAuth resource associated with the authorized connect - application, if one was requested. - example: https://api.example.com/resource - application: - $ref: '#/components/schemas/ConnectApplication' - required: - - object - - id - - granted_scopes - - application - 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: authorized_connect_app_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: authorized_connect_app_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - NewConnectApplicationSecret: - type: object - properties: - object: - type: string - description: Distinguishes the connect application secret object. - const: connect_application_secret - id: - type: string - description: The unique ID of the client secret. - example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q - secret_hint: - type: string - description: A hint showing the last few characters of the secret value. - example: abc123 - last_used_at: - type: - - string - - 'null' - description: >- - The timestamp when the client secret was last used, or null if never - used. - example: null - 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' - secret: - type: string - description: >- - The plaintext secret value. Only returned at creation time and - cannot be retrieved later. - example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz - required: - - object - - id - - secret_hint - - last_used_at - - created_at - - updated_at - - secret - AuditLogEventCreateResponse: - type: object - properties: - success: - type: boolean - description: Whether the Audit Log event was created successfully. - example: true - required: - - success - AuditLogExportJson: - type: object - properties: - object: - type: string - description: Distinguishes the Audit Log Export object. - example: audit_log_export - const: audit_log_export - id: - type: string - description: The unique ID of the Audit Log Export. - example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V - state: - type: string - enum: - - pending - - ready - - error - description: 'The state of the export. Possible values: pending, ready, error.' - example: ready - url: - type: - - string - - 'null' - description: >- - A URL to the CSV file. Only defined when the Audit Log Export is - ready. - example: https://exports.audit-logs.com/audit-log-exports/export.csv - 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 - - state - - created_at - - updated_at - AuditLogsRetentionJson: - type: object - properties: - retention_period_in_days: - type: - - integer - - 'null' - description: >- - The number of days Audit Log events will be retained before being - permanently deleted. Valid values are 30 and 365. - example: 30 - required: - - retention_period_in_days - AuditLogSchemaJson: - type: object - properties: - object: - type: string - description: Distinguishes the Audit Log Schema object. - example: audit_log_schema - const: audit_log_schema - version: - type: integer - description: The version of the schema. - example: 1 - actor: - type: object - properties: - metadata: - type: object - additionalProperties: {} - description: The JSON Schema definition for actor metadata. - required: - - metadata - description: The metadata schema for the actor. - example: - metadata: - type: object - properties: - role: - type: string - targets: - type: array - items: - type: object - properties: - type: - type: string - description: The type of the target resource. - example: invoice - metadata: - type: object - additionalProperties: {} - description: Additional data associated with the event or entity. - example: - type: object - properties: - cost: - type: number - required: - - type - description: The list of targets for the schema. - example: - - type: invoice - metadata: - type: object - properties: - cost: - type: number - metadata: - type: object - additionalProperties: {} - description: Additional data associated with the event or entity. - example: - type: object - properties: - transactionId: - type: string - created_at: - format: date-time - type: string - description: The timestamp when the Audit Log Schema was created. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - version - - targets - - created_at - AuditLogActionJson: - type: object - properties: - object: - type: string - description: Distinguishes the Audit Log Action object. - example: audit_log_action - const: audit_log_action - name: - type: string - description: Identifier of what action was taken. - example: user.viewed_invoice - schema: - $ref: '#/components/schemas/AuditLogSchemaJson' - description: The schema associated with the action. - 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 - - name - - schema - - created_at - - updated_at - AuthenticationChallenge: - type: object - properties: - object: - type: string - description: Distinguishes the authentication challenge object. - const: authentication_challenge - id: - type: string - description: The unique ID of the authentication challenge. - example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ - expires_at: - format: date-time - type: string - description: >- - The timestamp when the challenge will expire. Does not apply to TOTP - factors. - example: '2026-01-15T12:00:00.000Z' - code: - type: string - description: The one-time code for the challenge. - example: '123456' - authentication_factor_id: - type: string - description: The unique ID of the authentication factor the challenge belongs to. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - 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 - - authentication_factor_id - - created_at - - updated_at - AuthenticationChallengeVerifyResponse: - type: object - properties: - challenge: - $ref: '#/components/schemas/AuthenticationChallenge' - description: The authentication challenge object. - valid: - type: boolean - description: Whether the code was valid. - example: true - required: - - challenge - - valid - AuthenticationFactorEnrolled: - type: object - properties: - object: - type: string - description: Distinguishes the authentication factor object. - const: authentication_factor - id: - type: string - description: The unique ID of the factor. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - type: - type: string - enum: - - generic_otp - - sms - - totp - - webauthn - description: The type of the factor to enroll. - example: totp - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C56J083X43JQXF3JK5 - sms: - type: object - properties: - phone_number: - type: string - description: The user's phone number for SMS-based authentication. - example: '+15005550006' - required: - - phone_number - description: SMS-based authentication factor details. - totp: - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in the user's - authenticator app. Defaults to your WorkOS team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their authenticator app. - Defaults to the user's email. - example: user@example.com - secret: - type: string - description: >- - TOTP secret that can be manually entered into some authenticator - apps in place of scanning a QR code. - example: JBSWY3DPEHPK3PXP - qr_code: - type: string - description: Base64 encoded image containing scannable QR code. - example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... - uri: - type: string - description: The `otpauth` URI that is encoded by the provided `qr_code`. - example: >- - otpauth://totp/WorkOS:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WorkOS - required: - - issuer - - user - - secret - - qr_code - - uri - description: >- - TOTP-based authentication factor details. Includes enrollment - secrets only available at creation time. - 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 - - type - - created_at - - updated_at - AuthenticationFactor: - type: object - properties: - object: - type: string - description: Distinguishes the authentication factor object. - const: authentication_factor - id: - type: string - description: The unique ID of the factor. - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ - type: - type: string - enum: - - generic_otp - - sms - - totp - - webauthn - description: The type of the factor to enroll. - example: totp - user_id: - type: string - description: The ID of the [user](/reference/authkit/user). - example: user_01E4ZCR3C56J083X43JQXF3JK5 - sms: - type: object - properties: - phone_number: - type: string - description: The user's phone number for SMS-based authentication. - example: '+15005550006' - required: - - phone_number - description: SMS-based authentication factor details. - totp: - type: object - properties: - issuer: - type: string - description: >- - Your application or company name displayed in the user's - authenticator app. Defaults to your WorkOS team name. - example: WorkOS - user: - type: string - description: >- - The user's account name displayed in their authenticator app. - Defaults to the user's email. - example: user@example.com - required: - - issuer - - user - description: TOTP-based authentication factor details. - 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 - - type - - created_at - - updated_at - AuthorizationCheck: - type: object - properties: - authorized: - type: boolean - description: >- - Whether the organization membership has the specified permission on - the resource. - example: true - required: - - authorized - AuthorizationResource: - type: object - properties: - object: - type: string - description: Distinguishes the Resource object. - const: authorization_resource - name: - type: string - description: A human-readable name for the Resource. - example: Website Redesign - description: - type: - - string - - 'null' - description: An optional description of the Resource. - example: Company website redesign project - organization_id: - type: string - description: The ID of the organization that owns the resource. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - parent_resource_id: - type: - - string - - 'null' - description: The ID of the parent resource, if this resource is nested. - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: An identifier you provide to reference the resource in your system. - example: proj-456 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: project - 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 - - name - - description - - organization_id - - parent_resource_id - - id - - external_id - - resource_type_slug - - created_at - - updated_at - AuthorizationResourceList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/AuthorizationResource' - 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: authz_resource_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: authz_resource_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - AuthorizationPermission: - type: object - properties: - object: - type: string - description: Distinguishes the Permission object. - const: permission - id: - type: string - description: Unique identifier of the Permission. - example: perm_01HXYZ123456789ABCDEFGHIJ - slug: - type: string - description: >- - A unique key to reference the permission. Must be lowercase and - contain only letters, numbers, hyphens, underscores, colons, - periods, and asterisks. - example: documents:read - name: - type: string - description: A descriptive name for the Permission. - example: View Documents - description: - type: - - string - - 'null' - description: An optional description of the Permission. - example: Allows viewing document contents - system: - type: boolean - description: >- - Whether the permission is a system permission. System permissions - are managed by WorkOS and cannot be deleted. - example: false - resource_type_slug: - type: string - description: The slug of the resource type associated with the permission. - example: workspace - 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 - - slug - - name - - description - - system - - resource_type_slug - - created_at - - updated_at - AuthorizationPermissionList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/AuthorizationPermission' - 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: perm_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: perm_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - 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. - RoleAssignment: - type: object - properties: - object: - type: string - description: Distinguishes the role assignment object. - const: role_assignment - id: - type: string - description: Unique identifier of the role assignment. - example: role_assignment_01HXYZ123456789ABCDEFGH - role: - $ref: '#/components/schemas/SlimRole' - description: The role included in the assignment. - resource: - type: object - properties: - id: - type: string - description: The unique ID of the Resource. - example: authz_resource_01HXYZ123456789ABCDEFGH - external_id: - type: string - description: >- - An identifier you provide to reference the resource in your - system. - example: proj-456 - resource_type_slug: - type: string - description: The slug of the resource type this resource belongs to. - example: project - required: - - id - - external_id - - resource_type_slug - description: The resource to which the role is assigned. - 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 - - role - - resource - - created_at - - updated_at - RoleAssignmentList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/RoleAssignment' - 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: role_assignment_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: role_assignment_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - Role: - type: object - properties: - slug: - type: string - description: A unique slug for the role. - example: admin - object: - type: string - description: Distinguishes the role object. - example: role - const: role - id: - type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 - name: - type: string - description: A descriptive name for the role. - example: Admin - description: - type: - - string - - 'null' - description: An optional description of the role. - example: Can manage all resources - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole - description: >- - Whether the role is scoped to the environment or an organization - (custom role). - example: EnvironmentRole - resource_type_slug: - type: string - description: The slug of the resource type the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - 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: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - RoleList: - type: object - properties: - object: - type: string - example: list - const: list - data: - type: array - items: - $ref: '#/components/schemas/Role' - description: The list of records for the current page. - required: - - object - - data - UserlandUser: - type: object - properties: - object: - type: string - description: Distinguishes the user object. - const: user - id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - 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 - profile_picture_url: - type: - - string - - 'null' - description: A URL reference to an image representing the user. - example: https://workoscdn.com/images/v1/123abc - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - email_verified: - type: boolean - description: Whether the user's email has been verified. - example: true - external_id: - type: - - string - - 'null' - description: The external ID of the user. - example: f1ffa2b2-c20b-4d39-be5c-212726e11222 - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: Object containing metadata key/value pairs associated with the user. - example: - timezone: America/New_York - propertyNames: - maxLength: 40 - maxProperties: 50 - last_sign_in_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the user last signed in. - example: '2025-06-25T19:07:33.155Z' - locale: - type: - - string - - 'null' - description: The user's preferred locale. - example: en-US - 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 - - first_name - - last_name - - profile_picture_url - - email - - email_verified - - external_id - - last_sign_in_at - - created_at - - updated_at - description: The user object. - UserlandUserOrganizationMembershipBaseWithUser: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of `active`, - `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a directory sync - connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the linked - [Directory User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User attributes take - precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - user: - $ref: '#/components/schemas/UserlandUser' - description: The user that belongs to the organization through this membership. - required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - user - UserlandUserOrganizationMembershipBaseWithUserList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: >- - #/components/schemas/UserlandUserOrganizationMembershipBaseWithUser - 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: om_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: om_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - Connection: - type: object - properties: - object: - type: string - description: Distinguishes the Connection object. - const: connection - id: - type: string - description: Unique identifier for the Connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: >- - Unique identifier for the Organization in which the Connection - resides. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_type: - type: string - enum: - - Pending - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: >- - The type of the SSO Connection used to authenticate the user. The - Connection type may be used to dynamically generate authorization - URLs. - example: OktaSAML - name: - type: string - description: >- - A human-readable name for the Connection. This will most commonly be - the organization's name. - example: Foo Corp - state: - type: string - enum: - - requires_type - - draft - - active - - validating - - inactive - - deleting - description: Indicates whether a Connection is able to authenticate users. - example: active - status: - type: string - enum: - - linked - - unlinked - description: Deprecated. Use `state` instead. - deprecated: true - example: linked - domains: - type: array - items: - type: object - properties: - id: - type: string - description: Unique identifier for the Connection Domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - object: - type: string - description: Distinguishes the Connection Domain object. - const: connection_domain - domain: - type: string - description: The domain value. - example: foo-corp.com - required: - - id - - object - - domain - description: List of Organization Domains. - options: - type: object - properties: - signing_cert: - type: - - string - - 'null' - description: The signing certificate of the SAML connection. - example: null - required: - - signing_cert - description: >- - Configuration options for SAML connections. Only present for SAML - connection types. - 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 - - connection_type - - name - - state - - status - - domains - - created_at - - updated_at - ConnectionList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/Connection' - 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: conn_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: conn_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - - list_metadata - CorsOriginResponse: - type: object - properties: - object: - type: string - description: Distinguishes the CORS origin object. - const: cors_origin - id: - type: string - description: Unique identifier of the CORS origin. - example: cors_origin_01HXYZ123456789ABCDEFGHIJ - origin: - type: string - description: The origin URL. - example: https://example.com - created_at: - type: string - format: date-time - description: Timestamp when the CORS origin was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - format: date-time - description: Timestamp when the CORS origin was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - origin - - created_at - - updated_at - Directory: - type: object - properties: - object: - type: string - description: Distinguishes the Directory object. - const: directory - id: - type: string - description: Unique identifier for the Directory. - example: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: - type: string - description: >- - The unique identifier for the Organization in which the directory - resides. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - external_key: - type: string - description: External Key for the Directory. - example: sPa12dwRQ - type: - description: The type of external Directory Provider integrated with. - example: gsuite directory - type: string - enum: - - azure scim v2.0 - - bamboohr - - breathe hr - - cezanne hr - - cyberark scim v2.0 - - fourth hr - - generic scim v2.0 - - gsuite directory - - hibob - - sailpoint scim v2.0 - - jump cloud scim v2.0 - - okta scim v2.0 - - onelogin scim v2.0 - - people hr - - personio - - pingfederate scim v2.0 - - rippling scim v2.0 - - s3 - - sftp - - sftp workday - - workday - state: - description: >- - Describes whether the Directory has been successfully connected to - an external provider. - example: linked - type: string - enum: - - linked - - validating - - invalid_credentials - - unlinked - - deleting - name: - type: string - description: The name of the directory. - example: Foo Corp - domain: - type: string - description: The URL associated with an Enterprise Client. - example: foo-corp.com - metadata: - type: object - properties: - users: - type: object - properties: - active: - type: integer - description: Count of active directory users. - example: 42 - inactive: - type: integer - description: Count of inactive directory users. - example: 3 - required: - - active - - inactive - description: Counts of active and inactive directory users. - groups: - type: integer - description: Count of directory groups. - example: 5 - required: - - users - - groups - description: >- - Aggregate counts of directory users and groups synced from the - 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 - - organization_id - - external_key - - type - - state - - name - - created_at - - updated_at - DirectoryList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/Directory' - 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_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_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 - DirectoryGroupList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/DirectoryGroup' - 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_group_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_group_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - - list_metadata - 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 - 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 - UserlandUserOrganizationMembershipBaseList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of `active`, - `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a directory - sync connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the linked - [Directory User](/reference/directory-sync/directory-user) or - [SSO Profile](/reference/sso/profile). Directory User - attributes take precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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 - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - 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: om_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: om_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - Group: - type: object - properties: - object: - type: string - description: The Group object. - example: group - const: group - id: - type: string - description: The unique ID of the Group. - example: group_01HXYZ123456789ABCDEFGHIJ - organization_id: - type: string - description: The ID of the Organization the Group belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: The name of the Group. - example: Engineering - description: - type: - - string - - 'null' - description: An optional description of the Group. - example: The engineering team - 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 - - organization_id - - name - - description - - created_at - - updated_at - GroupList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/Group' - 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: group_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: group_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - EventContextActorDto: - type: object - properties: - id: - type: string - description: Unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - source: - type: string - enum: - - api - - dashboard - - admin_portal - - system - description: The source of the actor that performed the action. - name: - type: - - string - - 'null' - description: The name of the actor. - example: Jane Doe - required: - - id - - source - - name - description: The actor who performed the action. - EventContextDto: - type: object - properties: - google_analytics_client_id: - type: string - description: The Google Analytics client ID. - example: GA1.2.1234567890.1234567890 - google_analytics_sessions: - type: array - items: - type: object - properties: - containerId: - type: string - description: The Google Analytics container ID. - example: GTM-ABCDEF - sessionId: - type: string - description: The Google Analytics session ID. - example: '1234567890' - sessionNumber: - type: string - description: The Google Analytics session number. - example: '1' - required: - - containerId - description: The Google Analytics sessions associated with the event. - ajs_anonymous_id: - type: string - description: The anonymous ID from analytics. - example: ajs_anon_01EHWNCE74X7JSDV0X3SZ3KJNY - client_id: - type: string - description: The client ID associated with the event. - example: client_01EHWNCE74X7JSDV0X3SZ3KJNY - actor: - $ref: '#/components/schemas/EventContextActorDto' - previous_attributes: - type: object - additionalProperties: {} - description: Attributes that changed from their previous values. - description: Additional context about the event. - DirectoryUser: - 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: &ref_18 - 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' - required: - - object - - id - - directory_id - - organization_id - - idp_id - - email - - state - - raw_attributes - - custom_attributes - - created_at - - updated_at - WaitlistUser: - type: object - properties: - object: - type: string - description: Distinguishes the Waitlist User object. - const: waitlist_user - id: - type: string - description: The unique ID of the Waitlist User. - example: wl_user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the Waitlist User. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - approved - - denied - description: The state of the Waitlist User. - example: pending - approved_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the Waitlist User was approved, or null if not - yet approved. - example: null - 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 - - email - - state - - approved_at - - created_at - - updated_at - EventSchema: - allOf: - - type: object - properties: - object: - type: string - description: Distinguishes the Event object. - const: event - id: - type: string - description: Unique identifier for the Event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - description: The type of event that occurred. - example: dsync.user.created - data: - type: object - additionalProperties: {} - description: The event payload. - example: &ref_16 - id: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ - directory_id: directory_01ECAZ4NV9QMV47GW873HDCX74 - organization_id: org_01EZTR6WYX1A0DSE2CYMGXQ24Y - state: active - email: veda@foo-corp.com - emails: - - primary: true - type: work - value: veda@foo-corp.com - idp_id: '2836' - object: directory_user - username: veda@foo-corp.com - last_name: Torp - first_name: Veda - raw_attributes: {} - custom_attributes: {} - created_at: '2021-06-25T19:07:33.155Z' - updated_at: '2021-06-25T19:07:33.155Z' - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - type: object - additionalProperties: {} - description: Additional context about the event. - required: - - object - - id - - event - - data - - created_at - description: An event emitted by WorkOS. - example: &ref_23 - object: event - id: event_01EHZNVPK3SFK441A1RGBFSHRT - event: dsync.user.created - data: *ref_16 - created_at: '2021-06-25T19:07:33.155Z' - context: {} - - oneOf: - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: action.authentication.denied - data: - type: object - properties: - action_endpoint_id: - type: string - description: The ID of the action endpoint. - example: action_endpoint_01EHWNCE74X7JSDV0X3SZ3KJNY - action_execution_id: - type: string - description: The ID of the action execution. - example: action_execution_01EHWNCE74X7JSDV0X3SZ3KJNY - type: - type: string - description: The type of action that was denied. - const: authentication - verdict: - type: string - description: The verdict of the action. - const: Deny - user_id: - type: string - description: The ID of the user. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: - - string - - 'null' - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - email: - type: string - description: The email address of the user. - example: user@example.com - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.1 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - required: - - action_endpoint_id - - action_execution_id - - type - - verdict - - user_id - - organization_id - - email - - ip_address - - user_agent - description: The event payload. - context: - $ref: '#/components/schemas/EventContextDto' - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: action.user_registration.denied - data: - type: object - properties: - action_endpoint_id: - type: string - description: The ID of the action endpoint. - example: action_endpoint_01EHWNCE74X7JSDV0X3SZ3KJNY - action_execution_id: - type: string - description: The ID of the action execution. - example: action_execution_01EHWNCE74X7JSDV0X3SZ3KJNY - type: - type: string - description: The type of action that was denied. - const: user_registration - verdict: - type: string - description: The verdict of the action. - const: Deny - organization_id: - type: - - string - - 'null' - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - email: - type: string - description: The email address of the user. - example: user@example.com - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.1 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - required: - - action_endpoint_id - - action_execution_id - - type - - verdict - - organization_id - - email - - ip_address - - user_agent - description: The event payload. - context: - $ref: '#/components/schemas/EventContextDto' - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: api_key.created - data: - 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_01EHWNCE74X7JSDV0X3SZ3KJNY - owner: - oneOf: - - type: object - properties: - type: - type: string - description: The type of the API key owner. - const: organization - id: - type: string - description: The unique identifier of the API key owner. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - type - - id - - type: object - properties: - type: - type: string - description: The type of the API key owner. - const: user - id: - type: string - description: >- - The unique identifier of the user who owns the - API key. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: >- - The unique identifier of the organization the - API key belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - type - - id - - organization_id - description: The owner of the API key. - name: - type: string - description: The name of the API key. - example: My API Key - obfuscated_value: - type: string - description: The obfuscated value of the API key. - example: sk_test_...1234 - last_used_at: - type: - - string - - 'null' - description: The timestamp when the API key was last used. - example: '2026-01-15T12:00:00.000Z' - permissions: - type: array - items: - type: string - description: The permissions granted to the API key. - example: &ref_17 - - users:read - - users:write - created_at: - type: string - description: The timestamp when the API key was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - description: The timestamp when the API key was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - owner - - name - - obfuscated_value - - last_used_at - - permissions - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: api_key.revoked - data: - 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_01EHWNCE74X7JSDV0X3SZ3KJNY - owner: - oneOf: - - type: object - properties: - type: - type: string - description: The type of the API key owner. - const: organization - id: - type: string - description: The unique identifier of the API key owner. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - type - - id - - type: object - properties: - type: - type: string - description: The type of the API key owner. - const: user - id: - type: string - description: >- - The unique identifier of the user who owns the - API key. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: >- - The unique identifier of the organization the - API key belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - type - - id - - organization_id - description: The owner of the API key. - name: - type: string - description: The name of the API key. - example: My API Key - obfuscated_value: - type: string - description: The obfuscated value of the API key. - example: sk_test_...1234 - last_used_at: - type: - - string - - 'null' - description: The timestamp when the API key was last used. - example: '2026-01-15T12:00:00.000Z' - permissions: - type: array - items: - type: string - description: The permissions granted to the API key. - example: *ref_17 - created_at: - type: string - description: The timestamp when the API key was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - description: The timestamp when the API key was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - owner - - name - - obfuscated_value - - last_used_at - - permissions - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.email_verification_failed - data: - type: object - properties: - type: - type: string - const: email_verification - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.email_verification_succeeded - data: - type: object - properties: - type: - type: string - const: email_verification - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.magic_auth_failed - data: - type: object - properties: - type: - type: string - const: magic_auth - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.magic_auth_succeeded - data: - type: object - properties: - type: - type: string - const: magic_auth - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.mfa_failed - data: - type: object - properties: - type: - type: string - const: mfa - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.mfa_succeeded - data: - type: object - properties: - type: - type: string - const: mfa - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.oauth_failed - data: - type: object - properties: - type: - type: string - const: oauth - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.oauth_succeeded - data: - type: object - properties: - type: - type: string - const: oauth - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.passkey_failed - data: - type: object - properties: - type: - type: string - const: passkey - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.passkey_succeeded - data: - type: object - properties: - type: - type: string - const: passkey - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.password_failed - data: - type: object - properties: - type: - type: string - const: password - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.password_succeeded - data: - type: object - properties: - type: - type: string - const: password - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.radar_risk_detected - data: - type: object - properties: - auth_method: - type: string - description: The authentication method used. - example: password - action: - type: string - enum: - - signup - - login - control: - type: - - string - - 'null' - description: The control action taken for the detected risk. - example: block - blocklist_type: - type: - - string - - 'null' - description: The type of blocklist that triggered the risk detection. - example: ip - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - required: - - auth_method - - action - - control - - blocklist_type - - ip_address - - user_agent - - user_id - - email - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.sso_failed - data: - type: object - properties: - type: - type: string - const: sso - status: - type: string - const: failed - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - sso: - type: object - properties: - organization_id: - type: - - string - - 'null' - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_id: - type: - - string - - 'null' - description: The ID of the SSO connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - session_id: - type: - - string - - 'null' - description: The ID of the SSO session. - example: sess_01E4ZCR3C56J083X43JQXF3JK5 - required: - - organization_id - - connection_id - - session_id - description: SSO connection details. - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - sso - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.sso_started - data: - type: object - properties: - type: - type: string - const: sso - status: - type: string - const: started - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - sso: - type: object - properties: - organization_id: - type: - - string - - 'null' - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_id: - type: - - string - - 'null' - description: The ID of the SSO connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - session_id: - type: - - string - - 'null' - description: The ID of the SSO session. - example: sess_01E4ZCR3C56J083X43JQXF3JK5 - required: - - organization_id - - connection_id - - session_id - description: SSO connection details. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - sso - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.sso_succeeded - data: - type: object - properties: - type: - type: string - const: sso - status: - type: string - const: succeeded - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: user@example.com - sso: - type: object - properties: - organization_id: - type: - - string - - 'null' - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_id: - type: - - string - - 'null' - description: The ID of the SSO connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - session_id: - type: - - string - - 'null' - description: The ID of the SSO session. - example: sess_01E4ZCR3C56J083X43JQXF3JK5 - required: - - organization_id - - connection_id - - session_id - description: SSO connection details. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - sso - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: authentication.sso_timed_out - data: - type: object - properties: - type: - type: string - const: sso - status: - type: string - const: timed_out - ip_address: - type: - - string - - 'null' - description: The IP address of the request. - example: 203.0.113.42 - user_agent: - type: - - string - - 'null' - description: The user agent of the request. - example: Mozilla/5.0 - user_id: - type: - - string - - 'null' - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: - - string - - 'null' - description: The email address of the user. - example: user@example.com - sso: - type: object - properties: - organization_id: - type: - - string - - 'null' - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - connection_id: - type: - - string - - 'null' - description: The ID of the SSO connection. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - session_id: - type: - - string - - 'null' - description: The ID of the SSO session. - example: sess_01E4ZCR3C56J083X43JQXF3JK5 - required: - - organization_id - - connection_id - - session_id - description: SSO connection details. - error: - type: object - properties: - code: - type: string - description: The error code. - example: mfa_challenge_failed - message: - type: string - description: A human-readable error message. - example: The MFA challenge has failed. - required: - - code - - message - description: Details about the authentication error. - required: - - type - - status - - ip_address - - user_agent - - user_id - - email - - sso - - error - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: connection.activated - data: - type: object - properties: - object: - type: string - description: Distinguishes the connection object. - const: connection - id: - type: string - description: Unique identifier of the connection. - example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY - state: - type: string - enum: - - draft - - active - - validating - - inactive - - deleting - description: The current state of the connection. - example: active - name: - type: string - description: The name of the connection. - example: Acme SSO - connection_type: - type: string - enum: - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: The type of the connection. - example: OktaSAML - organization_id: - type: string - description: The ID of the organization the connection belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - 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' - external_key: - type: string - description: The external key of the connection. - example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY - status: - type: string - enum: - - linked - - unlinked - description: Deprecated. Use state instead. - example: linked - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the connection domain object. - const: connection_domain - id: - type: string - description: Unique identifier of the connection domain. - example: conn_domain_01EHWNCE74X7JSDV0X3SZ3KJNY - domain: - type: string - description: The domain value. - example: acme.com - required: - - object - - id - - domain - description: The domains associated with the connection. - required: - - object - - id - - state - - name - - connection_type - - created_at - - updated_at - - external_key - - status - - domains - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: connection.deactivated - data: - type: object - properties: - object: - type: string - description: Distinguishes the connection object. - const: connection - id: - type: string - description: Unique identifier of the connection. - example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY - state: - type: string - enum: - - draft - - active - - validating - - inactive - - deleting - description: The current state of the connection. - example: active - name: - type: string - description: The name of the connection. - example: Acme SSO - connection_type: - type: string - enum: - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: The type of the connection. - example: OktaSAML - organization_id: - type: string - description: The ID of the organization the connection belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - 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' - external_key: - type: string - description: The external key of the connection. - example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY - status: - type: string - enum: - - linked - - unlinked - description: Deprecated. Use state instead. - example: linked - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the connection domain object. - const: connection_domain - id: - type: string - description: Unique identifier of the connection domain. - example: conn_domain_01EHWNCE74X7JSDV0X3SZ3KJNY - domain: - type: string - description: The domain value. - example: acme.com - required: - - object - - id - - domain - description: The domains associated with the connection. - required: - - object - - id - - state - - name - - connection_type - - created_at - - updated_at - - external_key - - status - - domains - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: connection.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the connection object. - const: connection - id: - type: string - description: Unique identifier of the connection. - example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY - state: - type: string - enum: - - draft - - active - - validating - - inactive - - deleting - description: The current state of the connection. - example: active - name: - type: string - description: The name of the connection. - example: Acme SSO - connection_type: - type: string - enum: - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: The type of the connection. - example: OktaSAML - organization_id: - type: string - description: The ID of the organization the connection belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - 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 - - state - - name - - connection_type - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: connection.saml_certificate_renewal_required - data: - type: object - properties: - connection: - type: object - properties: - id: - type: string - description: Unique identifier of the connection. - example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: >- - The ID of the organization the connection belongs - to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - id - description: The connection with the expiring certificate. - certificate: - type: object - properties: - certificate_type: - type: string - enum: - - ResponseSigning - - RequestSigning - - ResponseEncryption - description: The type of the SAML certificate. - example: ResponseSigning - expiry_date: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - is_expired: - type: boolean - description: Whether the certificate has already expired. - example: false - required: - - certificate_type - - expiry_date - - is_expired - description: The SAML certificate details. - days_until_expiry: - type: integer - description: The number of days until the certificate expires. - example: 30 - required: - - connection - - certificate - - days_until_expiry - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: connection.saml_certificate_renewed - data: - type: object - properties: - connection: - type: object - properties: - id: - type: string - description: Unique identifier of the connection. - example: conn_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: >- - The ID of the organization the connection belongs - to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - id - description: The connection with the renewed certificate. - certificate: - type: object - properties: - certificate_type: - type: string - enum: - - ResponseSigning - - RequestSigning - - ResponseEncryption - description: The type of the SAML certificate. - example: ResponseSigning - expiry_date: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - required: - - certificate_type - - expiry_date - description: The renewed SAML certificate details. - renewed_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - required: - - connection - - certificate - - renewed_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.activated - data: - type: object - properties: - object: - type: string - description: Distinguishes the directory object. - const: directory - id: - type: string - description: Unique identifier of the directory. - example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: The ID of the organization the directory belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - type: - type: string - enum: - - azure scim v2.0 - - bamboohr - - breathe hr - - cezanne hr - - cyberark scim v2.0 - - fourth hr - - generic scim v2.0 - - gsuite directory - - gusto - - hibob - - jump cloud scim v2.0 - - okta scim v2.0 - - onelogin scim v2.0 - - people hr - - personio - - pingfederate scim v2.0 - - rippling scim v2.0 - - rippling - - sailpoint scim v2.0 - - s3 - - sftp - - sftp workday - - workday - description: The type of the directory. - example: okta scim v2.0 - state: - type: string - enum: - - active - - validating - - invalid_credentials - - inactive - - deleting - description: The current state of the directory. - example: active - name: - type: string - description: The name of the directory. - example: Acme Directory - 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' - external_key: - type: string - description: The external key of the directory. - example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHWNCE74X7JSDV0X3SZ3KJNY - domain: - type: string - description: The domain value. - example: acme.com - required: - - object - - id - - domain - description: The domains associated with the directory. - required: - - object - - id - - type - - state - - name - - created_at - - updated_at - - external_key - - domains - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.deactivated - data: - type: object - properties: - object: - type: string - description: Distinguishes the directory object. - const: directory - id: - type: string - description: Unique identifier of the directory. - example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: The ID of the organization the directory belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - type: - type: string - enum: - - azure scim v2.0 - - bamboohr - - breathe hr - - cezanne hr - - cyberark scim v2.0 - - fourth hr - - generic scim v2.0 - - gsuite directory - - gusto - - hibob - - jump cloud scim v2.0 - - okta scim v2.0 - - onelogin scim v2.0 - - people hr - - personio - - pingfederate scim v2.0 - - rippling scim v2.0 - - rippling - - sailpoint scim v2.0 - - s3 - - sftp - - sftp workday - - workday - description: The type of the directory. - example: okta scim v2.0 - state: - type: string - enum: - - active - - validating - - invalid_credentials - - inactive - - deleting - description: The current state of the directory. - example: active - name: - type: string - description: The name of the directory. - example: Acme Directory - 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' - external_key: - type: string - description: The external key of the directory. - example: ext_01EHWNCE74X7JSDV0X3SZ3KJNY - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHWNCE74X7JSDV0X3SZ3KJNY - domain: - type: string - description: The domain value. - example: acme.com - required: - - object - - id - - domain - description: The domains associated with the directory. - required: - - object - - id - - type - - state - - name - - created_at - - updated_at - - external_key - - domains - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the directory object. - const: directory - id: - type: string - description: Unique identifier of the directory. - example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: The ID of the organization the directory belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - type: - type: string - enum: - - azure scim v2.0 - - bamboohr - - breathe hr - - cezanne hr - - cyberark scim v2.0 - - fourth hr - - generic scim v2.0 - - gsuite directory - - gusto - - hibob - - jump cloud scim v2.0 - - okta scim v2.0 - - onelogin scim v2.0 - - people hr - - personio - - pingfederate scim v2.0 - - rippling scim v2.0 - - rippling - - sailpoint scim v2.0 - - s3 - - sftp - - sftp workday - - workday - description: The type of the directory. - example: okta scim v2.0 - state: - type: string - enum: - - active - - validating - - invalid_credentials - - inactive - - deleting - description: The current state of the directory. - example: active - name: - type: string - description: The name of the directory. - example: Acme Directory - 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 - - type - - state - - name - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.group.created - data: - $ref: '#/components/schemas/DirectoryGroup' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.group.deleted - data: - $ref: '#/components/schemas/DirectoryGroup' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.group.updated - data: - 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' - previous_attributes: - type: object - additionalProperties: {} - required: - - object - - id - - idp_id - - directory_id - - organization_id - - name - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.group.user_added - data: - type: object - properties: - directory_id: - type: string - description: The ID of the directory. - example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY - user: - $ref: '#/components/schemas/DirectoryUser' - description: The directory user added to the group. - group: - $ref: '#/components/schemas/DirectoryGroup' - description: The directory group the user was added to. - required: - - directory_id - - user - - group - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.user.created - data: - $ref: '#/components/schemas/DirectoryUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.user.deleted - data: - $ref: '#/components/schemas/DirectoryUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.group.user_removed - data: - type: object - properties: - directory_id: - type: string - description: The ID of the directory. - example: directory_01EHWNCE74X7JSDV0X3SZ3KJNY - user: - $ref: '#/components/schemas/DirectoryUser' - description: The directory user removed from the group. - group: - $ref: '#/components/schemas/DirectoryGroup' - description: The directory group the user was removed from. - required: - - directory_id - - user - - group - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: dsync.user.updated - data: - 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: *ref_18 - 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' - previous_attributes: - type: object - additionalProperties: {} - required: - - object - - id - - directory_id - - organization_id - - idp_id - - email - - state - - raw_attributes - - custom_attributes - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: email_verification.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the email verification object. - const: email_verification - id: - type: string - description: The unique ID of the email verification code. - example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the email verification code expires. - example: '2026-01-15T12:00:00.000Z' - 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 - - user_id - - email - - expires_at - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: flag.created - data: - type: object - properties: - object: - type: string - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - environment_id: - type: string - description: The ID of the environment the Feature Flag belongs to. - example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: A descriptive name for the Feature Flag. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: &ref_19 - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - environment_id - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - type: object - properties: - client_id: - type: string - description: The client ID associated with the flag event. - example: client_01EHWNCE74X7JSDV0X3SZ3KJNY - actor: - type: object - properties: - id: - type: string - description: Unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - source: - type: string - enum: - - api - - dashboard - - admin_portal - - system - description: The source of the actor that performed the action. - name: - type: - - string - - 'null' - description: The name of the actor. - example: Jane Doe - required: - - id - - source - - name - description: The actor who performed the action. - required: - - client_id - - actor - description: Additional context about the event. - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - context - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: flag.deleted - data: - type: object - properties: - object: - type: string - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - environment_id: - type: string - description: The ID of the environment the Feature Flag belongs to. - example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: A descriptive name for the Feature Flag. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: *ref_19 - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - environment_id - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - type: object - properties: - client_id: - type: string - description: The client ID associated with the flag event. - example: client_01EHWNCE74X7JSDV0X3SZ3KJNY - actor: - type: object - properties: - id: - type: string - description: Unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - source: - type: string - enum: - - api - - dashboard - - admin_portal - - system - description: The source of the actor that performed the action. - name: - type: - - string - - 'null' - description: The name of the actor. - example: Jane Doe - required: - - id - - source - - name - description: The actor who performed the action. - required: - - client_id - - actor - description: Additional context about the event. - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - context - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: flag.rule_updated - data: - type: object - properties: - object: - type: string - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - environment_id: - type: string - description: The ID of the environment the Feature Flag belongs to. - example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: A descriptive name for the Feature Flag. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: *ref_19 - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - environment_id - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - type: object - properties: - client_id: - type: string - description: The client ID associated with the flag event. - example: client_01EHWNCE74X7JSDV0X3SZ3KJNY - actor: - type: object - properties: - id: - type: string - description: Unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - source: - type: string - enum: - - api - - dashboard - - admin_portal - - system - name: - type: - - string - - 'null' - description: The name of the actor. - example: Jane Doe - required: - - id - - source - - name - description: The actor who performed the action. - access_type: - type: string - enum: - - none - - some - - all - description: The access type of the flag rule. - configured_targets: - type: object - properties: - organizations: - type: array - items: - type: object - properties: - id: - type: string - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: The name of the organization. - example: Acme Corp - required: - - id - - name - description: The organizations targeted by the flag rule. - users: - type: array - items: - type: object - properties: - id: - type: string - description: The ID of the user. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - email: - type: string - description: The email of the user. - example: user@example.com - required: - - id - - email - description: The users targeted by the flag rule. - required: - - organizations - - users - description: The configured targets for the flag rule. - previous_attributes: - type: object - properties: - data: - type: object - properties: - enabled: - type: boolean - description: Whether the flag was previously enabled. - example: true - default_value: - type: boolean - description: The previous default value of the flag. - example: false - description: The previous data attributes of the flag. - context: - type: object - properties: - access_type: - type: string - enum: - - none - - some - - all - description: The previous access type of the flag rule. - configured_targets: - type: object - properties: - organizations: - type: array - items: - type: object - properties: - id: - type: string - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: The name of the organization. - example: Acme Corp - required: - - id - - name - description: The organizations targeted by the flag rule. - users: - type: array - items: - type: object - properties: - id: - type: string - description: The ID of the user. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - email: - type: string - description: The email of the user. - example: user@example.com - required: - - id - - email - description: The users targeted by the flag rule. - required: - - organizations - - users - description: >- - The previous configured targets for the flag - rule. - description: The previous context attributes of the flag rule. - description: Attributes that changed from their previous values. - required: - - client_id - - actor - - access_type - - configured_targets - - previous_attributes - description: Additional context about the event. - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - context - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: flag.updated - data: - type: object - properties: - object: - type: string - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - environment_id: - type: string - description: The ID of the environment the Feature Flag belongs to. - example: environment_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: A descriptive name for the Feature Flag. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: >- - Labels assigned to the Feature Flag for categorizing and - filtering. - example: *ref_19 - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the - current environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't - match any configured targeting rules. - example: false - 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 - - environment_id - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - type: object - properties: - client_id: - type: string - description: The client ID associated with the flag event. - example: client_01EHWNCE74X7JSDV0X3SZ3KJNY - actor: - type: object - properties: - id: - type: string - description: Unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - source: - type: string - enum: - - api - - dashboard - - admin_portal - - system - description: The source of the actor that performed the action. - name: - type: - - string - - 'null' - description: The name of the actor. - example: Jane Doe - required: - - id - - source - - name - description: The actor who performed the action. - previous_attributes: - type: object - properties: - data: - type: object - properties: - name: - type: string - description: The previous name of the flag. - example: My Feature Flag - description: - type: - - string - - 'null' - description: The previous description of the flag. - example: Enables the new feature. - tags: - type: array - items: - type: string - description: The previous tags of the flag. - example: - - beta - - release - enabled: - type: boolean - description: Whether the flag was previously enabled. - example: true - default_value: - type: boolean - description: The previous default value of the flag. - example: false - description: The previous data attributes of the flag. - description: Attributes that changed from their previous values. - required: - - client_id - - actor - description: Additional context about the event. - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - context - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: group.created - data: - $ref: '#/components/schemas/Group' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: group.deleted - data: - $ref: '#/components/schemas/Group' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: group.member_added - data: - type: object - properties: - group_id: - type: string - description: The ID of the Group. - example: group_01HXYZ123456789ABCDEFGHIJ - organization_membership_id: - type: string - description: The ID of the OrganizationMembership. - example: om_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - group_id - - organization_membership_id - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: group.member_removed - data: - type: object - properties: - group_id: - type: string - description: The ID of the Group. - example: group_01HXYZ123456789ABCDEFGHIJ - organization_membership_id: - type: string - description: The ID of the OrganizationMembership. - example: om_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - group_id - - organization_membership_id - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: group.updated - data: - $ref: '#/components/schemas/Group' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: invitation.accepted - data: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null - if not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null - if not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) - that the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who invited the recipient, if - provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on - acceptance. Reflects the current role on the invitee's - organization membership. null when the invitation has no - associated organization. - example: admin - 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 - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: invitation.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null - if not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null - if not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) - that the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who invited the recipient, if - provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on - acceptance. Reflects the current role on the invitee's - organization membership. null when the invitation has no - associated organization. - example: admin - 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 - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: invitation.resent - data: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null - if not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null - if not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) - that the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who invited the recipient, if - provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on - acceptance. Reflects the current role on the invitee's - organization membership. null when the invitation has no - associated organization. - example: admin - 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 - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: invitation.revoked - data: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null - if not yet accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null - if not revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) - that the recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who invited the recipient, if - provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: >- - The ID of the user who accepted the invitation, once - accepted. - example: null - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on - acceptance. Reflects the current role on the invitee's - organization membership. null when the invitation has no - associated organization. - example: admin - 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 - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: magic_auth.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the Magic Auth object. - const: magic_auth - id: - type: string - description: The unique ID of the Magic Auth code. - example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the Magic Auth code expires. - example: '2026-01-15T12:00:00.000Z' - 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 - - user_id - - email - - expires_at - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) - key/value pairs associated with the Organization. - example: &ref_20 - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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 - - name - - domains - - metadata - - external_id - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) - key/value pairs associated with the Organization. - example: *ref_20 - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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 - - name - - domains - - metadata - - external_id - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_domain.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_domain.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_domain.updated - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_domain.verification_failed - data: - type: object - properties: - reason: - type: string - enum: - - domain_verification_period_expired - - domain_verified_by_other_organization - description: The reason the domain verification failed. - example: domain_verification_period_expired - organization_domain: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: The organization domain that failed verification. - required: - - reason - - organization_domain - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_domain.verified - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_membership.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: Unique identifier of the organization membership. - example: om_01EHWNCE74X7JSDV0X3SZ3KJNY - user_id: - type: string - description: The ID of the user. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - status: - type: string - enum: - - active - - inactive - - pending - description: The status of the organization membership. - example: active - role: - $ref: '#/components/schemas/SlimRole' - description: The role associated with the membership. - roles: - type: array - items: - $ref: '#/components/schemas/SlimRole' - description: The roles associated with the membership. - custom_attributes: - type: object - additionalProperties: {} - description: Custom attributes associated with the membership. - directory_managed: - type: boolean - description: >- - Whether the membership is managed by a directory sync - provider. - example: false - 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 - - user_id - - organization_id - - status - - role - - custom_attributes - - directory_managed - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_membership.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: Unique identifier of the organization membership. - example: om_01EHWNCE74X7JSDV0X3SZ3KJNY - user_id: - type: string - description: The ID of the user. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - status: - type: string - enum: - - active - - inactive - - pending - description: The status of the organization membership. - example: active - role: - $ref: '#/components/schemas/SlimRole' - description: The role associated with the membership. - roles: - type: array - items: - $ref: '#/components/schemas/SlimRole' - description: The roles associated with the membership. - custom_attributes: - type: object - additionalProperties: {} - description: Custom attributes associated with the membership. - directory_managed: - type: boolean - description: >- - Whether the membership is managed by a directory sync - provider. - example: false - 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 - - user_id - - organization_id - - status - - role - - custom_attributes - - directory_managed - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_membership.updated - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: Unique identifier of the organization membership. - example: om_01EHWNCE74X7JSDV0X3SZ3KJNY - user_id: - type: string - description: The ID of the user. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - organization_id: - type: string - description: The ID of the organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - status: - type: string - enum: - - active - - inactive - - pending - description: The status of the organization membership. - example: active - role: - $ref: '#/components/schemas/SlimRole' - description: The role associated with the membership. - roles: - type: array - items: - $ref: '#/components/schemas/SlimRole' - description: The roles associated with the membership. - custom_attributes: - type: object - additionalProperties: {} - description: Custom attributes associated with the membership. - directory_managed: - type: boolean - description: >- - Whether the membership is managed by a directory sync - provider. - example: false - 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 - - user_id - - organization_id - - status - - role - - custom_attributes - - directory_managed - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_role.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization role object. - const: organization_role - organization_id: - type: string - description: The ID of the organization the role belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: The slug identifier of the role. - example: billing-admin - name: - type: string - description: The name of the role. - example: Billing Administrator - description: - type: - - string - - 'null' - description: A description of the role. - example: Can manage billing settings. - resource_type_slug: - type: string - description: The slug of the resource type the role applies to. - example: organization - permissions: - type: array - items: - type: string - description: The permissions granted by the role. - example: &ref_21 - - users:read - - users: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 - - organization_id - - slug - - name - - description - - resource_type_slug - - permissions - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_role.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization role object. - const: organization_role - organization_id: - type: string - description: The ID of the organization the role belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: The slug identifier of the role. - example: billing-admin - name: - type: string - description: The name of the role. - example: Billing Administrator - description: - type: - - string - - 'null' - description: A description of the role. - example: Can manage billing settings. - resource_type_slug: - type: string - description: The slug of the resource type the role applies to. - example: organization - permissions: - type: array - items: - type: string - description: The permissions granted by the role. - example: *ref_21 - 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 - - organization_id - - slug - - name - - description - - resource_type_slug - - permissions - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization_role.updated - data: - type: object - properties: - object: - type: string - description: Distinguishes the organization role object. - const: organization_role - organization_id: - type: string - description: The ID of the organization the role belongs to. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: The slug identifier of the role. - example: billing-admin - name: - type: string - description: The name of the role. - example: Billing Administrator - description: - type: - - string - - 'null' - description: A description of the role. - example: Can manage billing settings. - resource_type_slug: - type: string - description: The slug of the resource type the role applies to. - example: organization - permissions: - type: array - items: - type: string - description: The permissions granted by the role. - example: *ref_21 - 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 - - organization_id - - slug - - name - - description - - resource_type_slug - - permissions - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: organization.updated - data: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does - not need to be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) - key/value pairs associated with the Organization. - example: *ref_20 - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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 - - name - - domains - - metadata - - external_id - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: password_reset.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the password reset object. - const: password_reset - id: - type: string - description: The unique ID of the password reset object. - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the password reset token expires. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: The timestamp when the password reset token was created. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - user_id - - email - - expires_at - - created_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: password_reset.succeeded - data: - type: object - properties: - object: - type: string - description: Distinguishes the password reset object. - const: password_reset - id: - type: string - description: The unique ID of the password reset object. - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the password reset token expires. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: The timestamp when the password reset token was created. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - user_id - - email - - expires_at - - created_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: permission.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the permission object. - const: permission - id: - type: string - description: Unique identifier of the permission. - example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: The slug identifier of the permission. - example: billing:manage - name: - type: string - description: The name of the permission. - example: Manage Billing - description: - type: - - string - - 'null' - description: A description of the permission. - example: Allows managing billing settings. - system: - type: boolean - description: Whether the permission is a system permission. - example: false - 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 - - slug - - name - - description - - system - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: permission.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the permission object. - const: permission - id: - type: string - description: Unique identifier of the permission. - example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: The slug identifier of the permission. - example: billing:manage - name: - type: string - description: The name of the permission. - example: Manage Billing - description: - type: - - string - - 'null' - description: A description of the permission. - example: Allows managing billing settings. - system: - type: boolean - description: Whether the permission is a system permission. - example: false - 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 - - slug - - name - - description - - system - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: permission.updated - data: - type: object - properties: - object: - type: string - description: Distinguishes the permission object. - const: permission - id: - type: string - description: Unique identifier of the permission. - example: perm_01EHWNCE74X7JSDV0X3SZ3KJNY - slug: - type: string - description: The slug identifier of the permission. - example: billing:manage - name: - type: string - description: The name of the permission. - example: Manage Billing - description: - type: - - string - - 'null' - description: A description of the permission. - example: Allows managing billing settings. - system: - type: boolean - description: Whether the permission is a system permission. - example: false - 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 - - slug - - name - - description - - system - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: role.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the role object. - const: role - slug: - type: string - description: The slug identifier of the role. - example: admin - resource_type_slug: - type: string - description: The slug of the resource type the role applies to. - example: organization - permissions: - type: array - items: - type: string - description: The permissions granted by the role. - example: &ref_22 - - users:read - - users: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 - - slug - - resource_type_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: role.deleted - data: - type: object - properties: - object: - type: string - description: Distinguishes the role object. - const: role - slug: - type: string - description: The slug identifier of the role. - example: admin - resource_type_slug: - type: string - description: The slug of the resource type the role applies to. - example: organization - permissions: - type: array - items: - type: string - description: The permissions granted by the role. - example: *ref_22 - 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 - - slug - - resource_type_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: role.updated - data: - type: object - properties: - object: - type: string - description: Distinguishes the role object. - const: role - slug: - type: string - description: The slug identifier of the role. - example: admin - resource_type_slug: - type: string - description: The slug of the resource type the role applies to. - example: organization - permissions: - type: array - items: - type: string - description: The permissions granted by the role. - example: *ref_22 - 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 - - slug - - resource_type_slug - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: session.created - data: - type: object - properties: - object: - type: string - description: Distinguishes the session object. - const: session - id: - type: string - description: The unique ID of the session. - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - impersonator: - type: object - properties: - email: - type: string - description: >- - The email address of the WorkOS Dashboard user who - is impersonating the user. - example: admin@foocorp.com - reason: - type: - - string - - 'null' - description: >- - The justification the impersonator gave for - impersonating the user. - example: Investigating an issue with the customer's account. - required: - - email - - reason - description: >- - Information about the impersonator if this session was - created via impersonation. - ip_address: - type: - - string - - 'null' - description: The IP address from which the session was created. - example: 198.51.100.42 - organization_id: - type: string - description: >- - The ID of the organization this session is associated - with. - example: org_01H945H0YD4F97JN9MATX7BYAG - user_agent: - type: - - string - - 'null' - description: >- - The user agent string from the device that created the - session. - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 - user_id: - type: string - description: The ID of the user this session belongs to. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - auth_method: - type: string - enum: - - cross_app_auth - - external_auth - - impersonation - - magic_code - - migrated_session - - oauth - - passkey - - password - - sso - - unknown - description: The authentication method used to create this session. - example: sso - status: - type: string - enum: - - active - - expired - - revoked - description: The current status of the session. - example: active - expires_at: - format: date-time - type: string - description: The timestamp when the session expires. - example: '2026-01-15T12:00:00.000Z' - ended_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the session ended. - example: null - 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 - - ip_address - - user_agent - - user_id - - auth_method - - status - - expires_at - - ended_at - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: session.revoked - data: - type: object - properties: - object: - type: string - description: Distinguishes the session object. - const: session - id: - type: string - description: The unique ID of the session. - example: session_01H93ZY4F80QPBEZ1R5B2SHQG8 - impersonator: - type: object - properties: - email: - type: string - description: >- - The email address of the WorkOS Dashboard user who - is impersonating the user. - example: admin@foocorp.com - reason: - type: - - string - - 'null' - description: >- - The justification the impersonator gave for - impersonating the user. - example: Investigating an issue with the customer's account. - required: - - email - - reason - description: >- - Information about the impersonator if this session was - created via impersonation. - ip_address: - type: - - string - - 'null' - description: The IP address from which the session was created. - example: 198.51.100.42 - organization_id: - type: string - description: >- - The ID of the organization this session is associated - with. - example: org_01H945H0YD4F97JN9MATX7BYAG - user_agent: - type: - - string - - 'null' - description: >- - The user agent string from the device that created the - session. - example: >- - Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) - AppleWebKit/537.36 - user_id: - type: string - description: The ID of the user this session belongs to. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - auth_method: - type: string - enum: - - cross_app_auth - - external_auth - - impersonation - - magic_code - - migrated_session - - oauth - - passkey - - password - - sso - - unknown - description: The authentication method used to create this session. - example: sso - status: - type: string - enum: - - active - - expired - - revoked - description: The current status of the session. - example: active - expires_at: - format: date-time - type: string - description: The timestamp when the session expires. - example: '2026-01-15T12:00:00.000Z' - ended_at: - format: date-time - type: - - string - - 'null' - description: The timestamp when the session ended. - example: null - 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 - - ip_address - - user_agent - - user_id - - auth_method - - status - - expires_at - - ended_at - - created_at - - updated_at - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: user.created - data: - $ref: '#/components/schemas/UserlandUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: user.deleted - data: - $ref: '#/components/schemas/UserlandUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: user.updated - data: - $ref: '#/components/schemas/UserlandUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.byok_key.deleted - data: - type: object - properties: - organization_id: - type: string - description: The unique identifier of the organization. - example: org_01EHT88Z8J8795GZNQ4ZP1J81T - key_provider: - type: string - enum: - - AWS_KMS - - GCP_KMS - - AZURE_KEY_VAULT - description: The external key provider used for BYOK. - example: AWS_KMS - required: - - organization_id - - key_provider - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.byok_key.verification_completed - data: - type: object - properties: - organization_id: - type: string - description: The unique identifier of the organization. - example: org_01EHT88Z8J8795GZNQ4ZP1J81T - key_provider: - type: string - enum: - - AWS_KMS - - GCP_KMS - - AZURE_KEY_VAULT - description: The external key provider used for BYOK. - example: AWS_KMS - verified: - type: boolean - description: >- - Whether the BYOK key verification completed - successfully. - example: true - required: - - organization_id - - key_provider - - verified - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.data.created - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - kv_name: - type: string - description: The name of the key-value store. - example: user-secrets - key_id: - type: string - description: The unique identifier of the encryption key. - example: key_01EHWNCE74X7JSDV0X3SZ3KJNY - key_context: - type: object - additionalProperties: - type: string - required: - - actor_id - - actor_source - - actor_name - - kv_name - - key_id - - key_context - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.data.deleted - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - kv_name: - type: string - description: The name of the key-value store. - example: user-secrets - required: - - actor_id - - actor_source - - actor_name - - kv_name - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.data.read - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - kv_name: - type: string - description: The name of the key-value store. - example: user-secrets - key_id: - type: string - description: The unique identifier of the encryption key. - example: key_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - actor_id - - actor_source - - actor_name - - kv_name - - key_id - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.data.updated - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - kv_name: - type: string - description: The name of the key-value store. - example: user-secrets - key_id: - type: string - description: The unique identifier of the encryption key. - example: key_01EHWNCE74X7JSDV0X3SZ3KJNY - key_context: - type: object - additionalProperties: - type: string - required: - - actor_id - - actor_source - - actor_name - - kv_name - - key_id - - key_context - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.dek.decrypted - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - key_id: - type: string - description: The unique identifier of the data encryption key. - example: key_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - actor_id - - actor_source - - actor_name - - key_id - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.dek.read - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - key_ids: - type: array - items: - type: string - description: The unique identifiers of the data encryption keys. - example: - - dek_01EHWNCE74X7JSDV0X3SZ3KJNY - key_context: - type: object - additionalProperties: - type: string - required: - - actor_id - - actor_source - - actor_name - - key_ids - - key_context - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.kek.created - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - key_name: - type: string - description: The name of the key encryption key. - example: production-kek - key_id: - type: string - description: The unique identifier of the key encryption key. - example: key_01EHWNCE74X7JSDV0X3SZ3KJNY - required: - - actor_id - - actor_source - - actor_name - - key_name - - key_id - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.metadata.read - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - kv_name: - type: string - description: The name of the key-value store. - example: user-secrets - required: - - actor_id - - actor_source - - actor_name - - kv_name - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: vault.names.listed - data: - type: object - properties: - actor_id: - type: string - description: The unique identifier of the actor. - example: user_01EHWNCE74X7JSDV0X3SZ3KJNY - actor_source: - type: string - enum: - - api - - dashboard - actor_name: - type: string - description: The name of the actor. - example: Jane Doe - required: - - actor_id - - actor_source - - actor_name - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: waitlist_user.approved - data: - $ref: '#/components/schemas/WaitlistUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: waitlist_user.created - data: - $ref: '#/components/schemas/WaitlistUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - - type: object - properties: - id: - type: string - description: Unique identifier for the event. - example: event_01EHZNVPK3SFK441A1RGBFSHRT - event: - type: string - const: waitlist_user.denied - data: - $ref: '#/components/schemas/WaitlistUser' - description: The event payload. - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - context: - $ref: '#/components/schemas/EventContextDto' - object: - type: string - description: Distinguishes the Event object. - const: event - required: - - id - - event - - data - - created_at - - object - example: *ref_23 - description: An event emitted by WorkOS. - EventList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/EventSchema' - description: The list of records for the current page. - list_metadata: - type: object - properties: - 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: event_01EHZNVPK3SFK441A1RGBFSHRT - required: - - after - description: Pagination cursor for navigating to the next page of results. - required: - - object - - data - - list_metadata - example: - object: list - data: - - *ref_23 - list_metadata: - after: event_01EHZNVPK3SFK441A1RGBFSHRT - JwtTemplate: - type: object - properties: - object: - type: string - description: The object type. - const: jwt_template - content: - type: string - description: The JWT template content as a Liquid template string. - example: >- - {"urn:myapp:full_name": "{{user.first_name}} {{user.last_name}}", - "urn:myapp:email": "{{user.email}}"} - created_at: - type: string - description: The timestamp when the JWT template was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - description: The timestamp when the JWT template was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - content - - created_at - - updated_at - OrganizationDomainStandAlone: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - Flag: - type: object - properties: - object: - type: string - description: Distinguishes the Feature Flag object. - const: feature_flag - id: - type: string - description: Unique identifier of the Feature Flag. - example: flag_01EHZNVPK3SFK441A1RGBFSHRT - slug: - type: string - description: A unique key to reference the Feature Flag. - example: advanced-analytics - name: - type: string - description: >- - A descriptive name for the Feature Flag. This field does not need to - be unique. - example: Advanced Analytics - description: - type: - - string - - 'null' - description: A description for the Feature Flag. - example: Enable advanced analytics dashboard feature - owner: - description: The owner of the Feature Flag. - oneOf: - - type: object - properties: - email: - type: string - description: The email address of the flag owner. - example: jane@example.com - first_name: - type: - - string - - 'null' - description: The first name of the flag owner. - example: Jane - last_name: - type: - - string - - 'null' - description: The last name of the flag owner. - example: Doe - required: - - email - - first_name - - last_name - - type: 'null' - tags: - type: array - items: - type: string - description: Labels assigned to the Feature Flag for categorizing and filtering. - example: - - reports - enabled: - type: boolean - description: >- - Specifies whether the Feature Flag is active for the current - environment. - example: true - default_value: - type: boolean - description: >- - The value returned for users and organizations who don't match any - configured targeting rules. - example: false - 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 - - slug - - name - - description - - owner - - tags - - enabled - - default_value - - created_at - - updated_at - FlagList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/Flag' - 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: flag_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: flag_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - OrganizationApiKey: - 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: organization - const: organization - id: - type: string - description: Unique identifier of the API Key owner. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - type - - 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 - OrganizationApiKeyList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/OrganizationApiKey' - 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 - OrganizationApiKeyWithValue: - 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: organization - const: organization - id: - type: string - description: Unique identifier of the API Key owner. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - required: - - type - - 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 - Organization: - type: object - properties: - object: - type: string - description: Distinguishes the Organization object. - const: organization - id: - type: string - description: Unique identifier of the Organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: >- - A descriptive name for the Organization. This field does not need to - be unique. - example: Acme Inc. - domains: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the organization domain object. - const: organization_domain - id: - type: string - description: Unique identifier of the organization domain. - example: org_domain_01EHZNVPK2QXHMVWCEDQEKY69A - organization_id: - type: string - description: ID of the parent Organization. - example: org_01HE8GSH8FQPASKSY27THRKRBP - domain: - type: string - description: Domain for the organization domain. - example: foo-corp.com - state: - type: string - enum: - - failed - - legacy_verified - - pending - - unverified - - verified - description: Verification state of the domain. - example: pending - verification_prefix: - type: string - description: The prefix used in DNS verification. - example: superapp-domain-verification-z3kjny - verification_token: - type: string - description: Validation token to be used in DNS TXT record. - example: m5Oztg3jdK4NJLgs8uIlIprMw - verification_strategy: - type: string - enum: - - dns - - manual - description: Strategy used to verify the domain. - example: dns - 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 - - organization_id - - domain - - created_at - - updated_at - description: List of Organization Domains. - metadata: - type: object - additionalProperties: - type: string - maxLength: 600 - description: >- - Object containing [metadata](/authkit/metadata) key/value pairs - associated with the Organization. - example: - tier: diamond - propertyNames: - maxLength: 40 - maxProperties: 50 - external_id: - type: - - string - - 'null' - description: The external ID of the Organization. - example: 2fe01467-f7ea-4dd2-8b79-c2b4f56d0191 - stripe_customer_id: - type: string - description: The Stripe customer ID of the Organization. - example: cus_R9qWAGMQ6nGE7V - 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' - allow_profiles_outside_organization: - type: boolean - description: >- - Whether the Organization allows profiles outside of its managed - domains. - example: false - deprecated: true - required: - - object - - id - - name - - domains - - metadata - - external_id - - created_at - - updated_at - OrganizationList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/Organization' - 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: org_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: org_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - - list_metadata - AuditLogConfiguration: - type: object - properties: - organization_id: - type: string - description: Unique identifier of the Organization. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - retention_period_in_days: - type: integer - description: >- - The number of days Audit Log events will be retained before being - permanently deleted. - example: 30 - state: - type: string - enum: - - active - - inactive - - disabled - description: >- - The current state of the audit log configuration for the - organization. - example: active - log_stream: - type: object - properties: - id: - type: string - description: Unique identifier of the Audit Log Stream. - example: als_01EHZNVPK3SFK441A1RGBFSHRT - type: - type: string - enum: - - AzureSentinel - - Datadog - - GenericHttps - - GoogleCloudStorage - - S3 - - Splunk - description: The type of the Audit Log Stream destination. - example: Datadog - state: - type: string - enum: - - active - - inactive - - error - - invalid - description: The current state of the Audit Log Stream. - example: active - last_synced_at: - type: - - string - - 'null' - description: >- - ISO-8601 timestamp of when the last event was successfully - synced, or null if no events have been synced. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - required: - - id - - type - - state - - last_synced_at - - created_at - description: >- - The Audit Log Stream currently configured for the organization, if - any. - required: - - organization_id - - retention_period_in_days - - state - DataIntegrationAuthorizeUrlResponse: - type: object - properties: - url: - type: string - description: The OAuth authorization URL to redirect the user to. - example: >- - https://api.workos.com/data-integrations/q2czJKmVAraSBg8xFpT7M9uR/authorize-redirect - required: - - url - DataIntegrationAccessTokenResponse: - oneOf: - - type: object - properties: - active: - type: boolean - description: >- - Indicates whether the access token is valid and ready for use, - or if reauthorization is required. - const: true - access_token: - type: object - properties: - object: - type: string - description: Distinguishes the access token object. - const: access_token - access_token: - type: string - description: The OAuth access token for the connected integration. - example: gho_16C7e42F292c6912E7710c838347Ae178B4a - expires_at: - type: - - string - - 'null' - description: >- - The ISO-8601 formatted timestamp indicating when the access - token expires. - example: '2025-12-31T23:59:59.000Z' - scopes: - type: array - items: - type: string - description: The scopes granted to the access token. - example: - - repo - - user:email - missing_scopes: - type: array - items: - type: string - description: >- - If the integration has requested scopes that aren't present - on the access token, they're listed here. - example: [] - required: - - object - - access_token - - expires_at - - scopes - - missing_scopes - description: >- - The [access token](/reference/pipes/access-token) object, - present when `active` is `true`. - required: - - active - - access_token - - type: object - properties: - active: - type: boolean - description: >- - Indicates whether the access token is valid and ready for use, - or if reauthorization is required. - const: false - error: - type: string - enum: - - needs_reauthorization - - not_installed - description: >- - - `"not_installed"`: The user does not have the integration - installed. - - - `"needs_reauthorization"`: The user needs to reauthorize the - integration. - example: not_installed - required: - - active - - error - ConnectedAccount: - type: object - properties: - object: - type: string - description: Distinguishes the connected account object. - const: connected_account - id: - type: string - description: The unique identifier of the connected account. - example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT - user_id: - type: - - string - - 'null' - description: >- - The [User](/reference/authkit/user) identifier associated with this - connection. - example: user_01EHZNVPK3SFK441A1RGBFSHRT - organization_id: - type: - - string - - 'null' - description: >- - The [Organization](/reference/organization) identifier associated - with this connection, or `null` if not scoped to an organization. - example: null - scopes: - type: array - items: - type: string - description: The OAuth scopes granted for this connection. - example: - - repo - - user:email - state: - type: string - enum: - - connected - - needs_reauthorization - - disconnected - description: >- - The state of the connected account: - - - `connected`: The connection is active and tokens are valid. - - - `needs_reauthorization`: The user needs to reauthorize the - connection, typically because required scopes have changed. - - - `disconnected`: The connection has been disconnected. - example: connected - created_at: - type: string - description: The timestamp when the connection was created. - example: '2024-01-16T14:20:00.000Z' - updated_at: - type: string - description: The timestamp when the connection was last updated. - example: '2024-01-16T14:20:00.000Z' - required: - - object - - id - - user_id - - organization_id - - scopes - - state - - created_at - - updated_at - DataIntegrationsListResponse: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - type: object - properties: - object: - type: string - description: Distinguishes the data provider object. - const: data_provider - id: - type: string - description: The unique identifier of the provider. - example: data_integration_01EHZNVPK3SFK441A1RGBFSHRT - name: - type: string - description: The display name of the provider (e.g., "GitHub", "Slack"). - example: GitHub - description: - type: - - string - - 'null' - description: >- - A description of the provider explaining how it will be used, - if configured. - example: Connect your GitHub account to access repositories. - slug: - type: string - description: >- - The slug identifier used in API calls (e.g., `github`, - `slack`, `notion`). - example: github - integration_type: - type: string - description: The type of integration (e.g., `github`, `slack`). - example: github - credentials_type: - type: string - description: The type of credentials used by the provider (e.g., `oauth2`). - example: oauth2 - scopes: - description: >- - The OAuth scopes configured for this provider, or `null` if - none are configured. - example: - - repo - - user:email - oneOf: - - type: array - items: - type: string - - type: 'null' - ownership: - type: string - enum: - - userland_user - - organization - description: Whether the provider is owned by a user or organization. - created_at: - type: string - description: The timestamp when the provider was created. - example: '2024-01-15T10:30:00.000Z' - updated_at: - type: string - description: The timestamp when the provider was last updated. - example: '2024-01-15T10:30:00.000Z' - integrationType: - type: string - deprecated: true - description: Use integration_type instead. - credentialsType: - type: string - deprecated: true - description: Use credentials_type instead. - createdAt: - type: string - deprecated: true - description: Use created_at instead. - updatedAt: - type: string - deprecated: true - description: Use updated_at instead. - connected_account: - description: >- - The user's [connected - account](/reference/pipes/connected-account) for this - provider, or `null` if the user has not connected. - oneOf: - - type: object - properties: - object: - type: string - description: Distinguishes the connected account object. - const: connected_account - id: - type: string - description: The unique identifier of the connected account. - example: data_installation_01EHZNVPK3SFK441A1RGBFSHRT - user_id: - type: - - string - - 'null' - description: >- - The [User](/reference/authkit/user) identifier - associated with this connection. - example: user_01EHZNVPK3SFK441A1RGBFSHRT - organization_id: - type: - - string - - 'null' - description: >- - The [Organization](/reference/organization) identifier - associated with this connection, or `null` if not - scoped to an organization. - example: null - scopes: - type: array - items: - type: string - description: The OAuth scopes granted for this connection. - example: - - repo - - user:email - state: - type: string - enum: - - connected - - needs_reauthorization - - disconnected - description: >- - The state of the connected account: - - - `connected`: The connection is active and tokens are - valid. - - - `needs_reauthorization`: The user needs to - reauthorize the connection, typically because required - scopes have changed. - - - `disconnected`: The connection has been - disconnected. - example: connected - created_at: - type: string - description: The timestamp when the connection was created. - example: '2024-01-16T14:20:00.000Z' - updated_at: - type: string - description: The timestamp when the connection was last updated. - example: '2024-01-16T14:20:00.000Z' - userlandUserId: - type: - - string - - 'null' - deprecated: true - description: Use `user_id` instead. - organizationId: - type: - - string - - 'null' - deprecated: true - description: Use `organization_id` instead. - createdAt: - type: string - deprecated: true - description: Use `created_at` instead. - updatedAt: - type: string - deprecated: true - description: Use `updated_at` instead. - required: - - object - - id - - user_id - - organization_id - - scopes - - state - - created_at - - updated_at - - userlandUserId - - organizationId - - createdAt - - updatedAt - - type: 'null' - required: - - object - - id - - name - - description - - slug - - integration_type - - credentials_type - - scopes - - ownership - - created_at - - updated_at - - integrationType - - credentialsType - - createdAt - - updatedAt - - connected_account - description: >- - A list of [providers](/reference/pipes/provider), each including a - [`connected_account`](/reference/pipes/connected-account) field with - the user's connection status. - required: - - object - - data - PortalLinkResponse: - type: object - properties: - link: - type: string - description: An ephemeral link to initiate the Admin Portal. - example: >- - https://setup.workos.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... - required: - - link - RadarStandaloneResponse: - type: object - properties: - verdict: - type: string - enum: - - allow - - block - - challenge - description: The verdict of the risk assessment. - example: block - reason: - type: string - description: A human-readable reason for the verdict. - example: Detected enabled Radar control - attempt_id: - type: string - description: Unique identifier of the authentication attempt. - example: radar_att_01HZBC6N1EB1ZY7KG32X - control: - type: string - enum: - - bot_detection - - brute_force_attack - - credential_stuffing - - domain_sign_up_rate_limit - - ip_sign_up_rate_limit - - impossible_travel - - repeat_sign_up - - stale_account - - unrecognized_device - - restriction - description: >- - The Radar control that triggered the verdict. Only present if the - verdict is `block` or `challenge`. - example: bot_detection - blocklist_type: - type: string - enum: - - ip_address - - domain - - email - - device - - user_agent - - device_fingerprint - - country - description: >- - The type of blocklist entry that triggered the verdict. Only present - if the control is `restriction`. - example: ip_address - required: - - verdict - - reason - - attempt_id - RadarListEntryAlreadyPresentResponse: - type: object - properties: - message: - type: string - description: A message indicating the entry already exists. - example: Entry already present in list - required: - - message - RedirectUri: - type: object - properties: - object: - type: string - description: The object type. - const: redirect_uri - id: - type: string - description: The ID of the redirect URI. - example: ruri_01EHZNVPK3SFK441A1RGBFSHRT - uri: - type: string - description: The redirect URI. - example: https://example.com/callback - default: - type: boolean - description: Whether this is the default redirect URI. - example: true - created_at: - type: string - description: The timestamp when the redirect URI was created. - example: '2026-01-15T12:00:00.000Z' - updated_at: - type: string - description: The timestamp when the redirect URI was last updated. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - id - - uri - - default - - created_at - - updated_at - UserlandUserAuthenticationFactorList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/AuthenticationFactor' - 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: auth_factor_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: auth_factor_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - UserlandUserAuthenticationFactorEnrollResponse: - type: object - properties: - authentication_factor: - $ref: '#/components/schemas/AuthenticationFactorEnrolled' - description: >- - The [authentication - factor](/reference/authkit/mfa/authentication-factor) object that - represents the additional authentication method used on top of the - existing authentication strategy. - authentication_challenge: - $ref: '#/components/schemas/AuthenticationChallenge' - description: >- - The [authentication - challenge](/reference/authkit/mfa/authentication-challenge) object - that is used to complete the authentication process. - required: - - authentication_factor - - authentication_challenge - MagicAuth: - type: object - properties: - object: - type: string - description: Distinguishes the Magic Auth object. - const: magic_auth - id: - type: string - description: The unique ID of the Magic Auth code. - example: magic_auth_01HWZBQZY2M3AMQW166Q22K88F - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the Magic Auth code expires. - example: '2026-01-15T12:00:00.000Z' - 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' - code: - type: string - description: The code used to verify the Magic Auth code. - example: '123456' - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - updated_at - - code - UserlandUserInvite: - type: object - properties: - object: - type: string - description: Distinguishes the invitation object. - const: invitation - id: - type: string - description: The unique ID of the invitation. - example: invitation_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the recipient. - example: marcelina.davis@example.com - state: - type: string - enum: - - pending - - accepted - - expired - - revoked - description: The state of the invitation. - example: pending - accepted_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was accepted, or null if not yet - accepted. - example: null - revoked_at: - format: date-time - type: - - string - - 'null' - description: >- - The timestamp when the invitation was revoked, or null if not - revoked. - example: null - expires_at: - format: date-time - type: string - description: The timestamp when the invitation expires. - example: '2026-01-15T12:00:00.000Z' - organization_id: - type: - - string - - 'null' - description: >- - The ID of the [organization](/reference/organization) that the - recipient will join. - example: org_01E4ZCR3C56J083X43JQXF3JK5 - inviter_user_id: - type: - - string - - 'null' - description: The ID of the user who invited the recipient, if provided. - example: user_01HYGBX8ZGD19949T3BM4FW1C3 - accepted_user_id: - type: - - string - - 'null' - description: The ID of the user who accepted the invitation, once accepted. - example: null - role_slug: - type: - - string - - 'null' - description: >- - Slug of the role the invitee will be assigned on acceptance. - Reflects the current role on the invitee's organization membership. - null when the invitation has no associated organization. - example: admin - 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' - token: - type: string - description: The token used to accept the invitation. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - accept_invitation_url: - type: string - description: The URL where the recipient can accept the invitation. - example: >- - https://your-app.com/invite?invitation_token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - email - - state - - accepted_at - - revoked_at - - expires_at - - organization_id - - inviter_user_id - - accepted_user_id - - role_slug - - created_at - - updated_at - - token - - accept_invitation_url - UserlandUserOrganizationMembership: - type: object - properties: - object: - type: string - description: Distinguishes the organization membership object. - const: organization_membership - id: - type: string - description: The unique ID of the organization membership. - example: om_01HXYZ123456789ABCDEFGHIJ - user_id: - type: string - description: The ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - organization_id: - type: string - description: The ID of the organization which the user belongs to. - example: org_01EHZNVPK3SFK441A1RGBFSHRT - status: - type: string - enum: - - active - - inactive - - pending - description: >- - The status of the organization membership. One of `active`, - `inactive`, or `pending`. - example: active - directory_managed: - type: boolean - description: >- - Whether this organization membership is managed by a directory sync - connection. - example: false - organization_name: - type: string - description: The name of the organization which the user belongs to. - example: Acme Corp - custom_attributes: - type: object - additionalProperties: {} - description: >- - An object containing IdP-sourced attributes from the linked - [Directory User](/reference/directory-sync/directory-user) or [SSO - Profile](/reference/sso/profile). Directory User attributes take - precedence when both are linked. - example: - department: Engineering - title: Developer Experience Engineer - location: Brooklyn - 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' - role: - $ref: '#/components/schemas/SlimRole' - description: The primary role assigned to the user within the organization. - user: - $ref: '#/components/schemas/UserlandUser' - description: The user that belongs to the organization through this membership. - required: - - object - - id - - user_id - - organization_id - - status - - directory_managed - - created_at - - updated_at - - role - - user - 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 - 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 - 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 - UserlandUserList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/UserlandUser' - 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: 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: user_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - EmailVerification: - type: object - properties: - object: - type: string - description: Distinguishes the email verification object. - const: email_verification - id: - type: string - description: The unique ID of the email verification code. - example: email_verification_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the email verification code expires. - example: '2026-01-15T12:00:00.000Z' - 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' - code: - type: string - description: The code used to verify the email. - example: '123456' - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - updated_at - - code - SendVerificationEmailResponse: - type: object - properties: - user: - $ref: '#/components/schemas/UserlandUser' - description: The user to whom the verification email was sent. - required: - - user - VerifyEmailResponse: - type: object - properties: - user: - $ref: '#/components/schemas/UserlandUser' - description: The user whose email was verified. - required: - - user - PasswordReset: - type: object - properties: - object: - type: string - description: Distinguishes the password reset object. - const: password_reset - id: - type: string - description: The unique ID of the password reset object. - example: password_reset_01E4ZCR3C56J083X43JQXF3JK5 - user_id: - type: string - description: The unique ID of the user. - example: user_01E4ZCR3C56J083X43JQXF3JK5 - email: - type: string - description: The email address of the user. - example: marcelina.davis@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the password reset token expires. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: The timestamp when the password reset token was created. - example: '2026-01-15T12:00:00.000Z' - password_reset_token: - type: string - description: The token used to reset the password. - example: Z1uX3RbwcIl5fIGJJJCXXisdI - password_reset_url: - type: string - description: The URL where the user can reset their password. - example: https://your-app.com/reset-password?token=Z1uX3RbwcIl5fIGJJJCXXisdI - required: - - object - - id - - user_id - - email - - expires_at - - created_at - - password_reset_token - - password_reset_url - ResetPasswordResponse: - type: object - properties: - user: - $ref: '#/components/schemas/UserlandUser' - description: The user whose password was reset. - required: - - user - EmailChange: - type: object - properties: - object: - type: string - description: Distinguishes the email change object. - const: email_change - user: - $ref: '#/components/schemas/UserlandUser' - new_email: - type: string - description: The new email address the user is changing to. - example: new.email@example.com - expires_at: - format: date-time - type: string - description: The timestamp when the email change code expires. - example: '2026-01-15T12:00:00.000Z' - created_at: - format: date-time - type: string - description: The timestamp when the email change challenge was created. - example: '2026-01-15T12:00:00.000Z' - required: - - object - - user - - new_email - - expires_at - - created_at - UserlandAuthenticateResponse: - type: object - properties: - user: - $ref: '#/components/schemas/UserlandUser' - description: The corresponding [user](/reference/authkit/user) object. - organization_id: - type: string - description: The ID of the organization the user selected to sign in to. - example: org_01H945H0YD4F97JN9MATX7BYAG - authkit_authorization_code: - type: string - description: >- - An authorization code that can be exchanged for tokens by a - different application. - example: authkit_authz_code_abc123 - access_token: - type: string - description: A JWT containing information about the current session. - example: eyJhb.nNzb19vaWRjX2tleV9.lc5Uk4yWVk5In0 - refresh_token: - type: string - description: >- - [Exchange this - token](/reference/authkit/authentication/refresh-token) for a new - access token. - example: yAjhKk123NLIjdrBdGZPf8pLIDvK - authentication_method: - type: string - enum: - - SSO - - Password - - Passkey - - AppleOAuth - - BitbucketOAuth - - CrossAppAuth - - DiscordOAuth - - ExternalAuth - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - IntuitOAuth - - LinkedInOAuth - - MicrosoftOAuth - - SalesforceOAuth - - SlackOAuth - - VercelMarketplaceOAuth - - VercelOAuth - - XeroOAuth - - MagicAuth - - Impersonation - - MigratedSession - description: The authentication method used to initiate the session. - example: SSO - impersonator: - type: object - properties: - email: - type: string - description: >- - The email address of the WorkOS Dashboard user who is - impersonating the user. - example: admin@foocorp.com - reason: - type: - - string - - 'null' - description: >- - The justification the impersonator gave for impersonating the - user. - example: Investigating an issue with the customer's account. - required: - - email - - reason - description: >- - Information about the impersonator if this session was created via - impersonation. - oauth_tokens: - type: object - properties: - provider: - type: string - description: The OAuth provider used for authentication. - example: GoogleOAuth - refresh_token: - type: string - description: The refresh token from the OAuth provider. - example: 1//04g... - access_token: - type: string - description: The access token from the OAuth provider. - example: ya29.a0ARrdaM... - expires_at: - type: integer - description: The timestamp at which the access token expires. - example: 1735141800 - scopes: - type: array - items: - type: string - description: A list of OAuth scopes for which the access token is authorized. - example: - - profile - - email - - openid - required: - - provider - - refresh_token - - access_token - - expires_at - - scopes - description: The OAuth tokens from the identity provider, if applicable. - required: - - user - - access_token - - refresh_token - DeviceAuthorizationResponse: - type: object - properties: - device_code: - type: string - description: The device verification code. - example: CVE2wOfIFK4vhmiDBntpX9s8KT2f0qngpWYL0LGy9HxYgBRXUKIUkZB9BgIFho5h - user_code: - type: string - description: The end-user verification code. - example: BCDF-GHJK - verification_uri: - type: string - format: uri - description: The end-user verification URI. - example: https://authkit_domain/device - verification_uri_complete: - type: string - format: uri - description: Verification URI that includes the user code. - example: https://authkit_domain/device?user_code=BCDF-GHJK - expires_in: - type: number - description: Lifetime in seconds of the codes. - example: 300 - interval: - type: number - description: Minimum polling interval in seconds. - example: 5 - required: - - device_code - - user_code - - verification_uri - - expires_in - WebhookEndpointJson: - type: object - properties: - object: - type: string - description: Distinguishes the Webhook Endpoint object. - const: webhook_endpoint - id: - type: string - description: Unique identifier of the Webhook Endpoint. - example: we_0123456789 - endpoint_url: - type: string - description: The URL to which webhooks are sent. - example: https://example.com/webhooks - secret: - type: string - description: The secret used to sign webhook payloads. - example: whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4 - status: - type: string - enum: - - enabled - - disabled - description: Whether the Webhook Endpoint is enabled or disabled. - example: enabled - events: - type: array - items: - type: string - description: The events that the Webhook Endpoint is subscribed to. - example: - - user.created - - dsync.user.created - 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 - - endpoint_url - - secret - - status - - events - - created_at - - updated_at - WebhookEndpointList: - type: object - properties: - object: - type: string - description: Indicates this is a list response. - const: list - data: - type: array - items: - $ref: '#/components/schemas/WebhookEndpointJson' - 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: we_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: we_01HXYZ987654321KJIHGFEDCBA - required: - - before - - after - description: Pagination cursors for navigating between pages of results. - required: - - object - - data - - list_metadata - WidgetSessionTokenResponse: - type: object - properties: - token: - type: string - description: The widget session token. - example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNlc3Npb24... - required: - - token - SsoAuthorizeUrlResponse: - type: object - properties: - url: - type: string - format: uri - description: An OAuth 2.0 authorization URL. - example: >- - https://accounts.google.com/o/oauth2/v2/auth?client_id=example&redirect_uri=https%3A%2F%2Fapi.workos.com%2Fsso%2Fcallback&response_type=code&scope=openid%20profile%20email - required: - - url - Profile: - type: object - properties: - object: - type: string - description: Distinguishes the profile object. - example: profile - const: profile - id: - type: string - description: Unique identifier of the profile. - example: prof_01DMC79VCBZ0NY2099737PSVF1 - organization_id: - type: - - string - - 'null' - description: The ID of the organization the user belongs to. - example: org_01EHQMYV6MBK39QC5PZXHY59C3 - connection_id: - type: string - description: The ID of the SSO connection used for authentication. - example: conn_01E4ZCR3C56J083X43JQXF3JK5 - connection_type: - type: string - enum: - - Pending - - ADFSSAML - - AdpOidc - - AppleOAuth - - Auth0Migration - - Auth0SAML - - AzureSAML - - BitbucketOAuth - - CasSAML - - ClassLinkSAML - - CleverOIDC - - CloudflareSAML - - CyberArkSAML - - DiscordOAuth - - DuoSAML - - EntraIdOIDC - - GenericOIDC - - GenericSAML - - GitHubOAuth - - GitLabOAuth - - GoogleOAuth - - GoogleOIDC - - GoogleSAML - - IntuitOAuth - - JumpCloudSAML - - KeycloakSAML - - LastPassSAML - - LinkedInOAuth - - LoginGovOidc - - MagicLink - - MicrosoftOAuth - - MiniOrangeSAML - - NetIqSAML - - OktaOIDC - - OktaSAML - - OneLoginSAML - - OracleSAML - - PingFederateSAML - - PingOneSAML - - RipplingSAML - - SalesforceSAML - - ShibbolethGenericSAML - - ShibbolethSAML - - SimpleSamlPhpSAML - - SalesforceOAuth - - SlackOAuth - - TestIdp - - VercelMarketplaceOAuth - - VercelOAuth - - VMwareSAML - - XeroOAuth - description: The type of SSO connection. - example: GoogleOAuth - idp_id: - type: string - description: The user's unique identifier from the identity provider. - example: '103456789012345678901' - email: - type: string - description: The user's email address. - example: todd@example.com - first_name: - type: - - string - - 'null' - description: The user's first name. - example: Todd - last_name: - type: - - string - - 'null' - description: The user's last name. - example: Rundgren - name: - type: - - string - - 'null' - description: The user's full name. - example: Todd Rundgren - role: - description: >- - The role assigned to the user within the organization, if - applicable. - oneOf: - - $ref: '#/components/schemas/SlimRole' - - type: 'null' - roles: - description: >- - The roles assigned to the user within the organization, if - applicable. - oneOf: - - type: array - items: - $ref: '#/components/schemas/SlimRole' - - type: 'null' - groups: - type: array - items: - type: string - description: >- - The groups the user belongs to, as returned by the identity - provider. - example: - - Engineering - - Admins - custom_attributes: - type: object - additionalProperties: {} - description: >- - Custom attribute mappings defined for the connection, returned as - key-value pairs. - raw_attributes: - type: object - additionalProperties: {} - description: >- - The complete set of raw attributes returned by the identity - provider. - required: - - object - - id - - organization_id - - connection_id - - connection_type - - idp_id - - email - - first_name - - last_name - - name - - raw_attributes - SsoTokenResponse: - type: object - properties: - token_type: - type: string - description: The type of token issued. - const: Bearer - access_token: - type: string - description: >- - An access token that can be exchanged for a user profile. Access - tokens are short-lived — see the `expires_in` field for the exact - lifetime. - example: eyJhbGciOiJSUzI1NiIsImtpZCI6InNzby... - expires_in: - type: integer - description: The lifetime of the access token in seconds. - example: 600 - profile: - $ref: '#/components/schemas/Profile' - description: The user profile returned by the identity provider. - oauth_tokens: - type: object - properties: - provider: - type: string - description: The OAuth provider used for authentication. - example: GoogleOAuth - refresh_token: - type: string - description: The refresh token from the OAuth provider. - example: 1//04g... - access_token: - type: string - description: The access token from the OAuth provider. - example: ya29.a0ARrdaM... - expires_at: - type: integer - description: The timestamp at which the access token expires. - example: 1735141800 - scopes: - type: array - items: - type: string - description: A list of OAuth scopes for which the access token is authorized. - example: - - profile - - email - - openid - required: - - provider - - refresh_token - - access_token - - expires_at - - scopes - description: OAuth tokens issued by the identity provider, if available. - required: - - token_type - - access_token - - expires_in - - profile - SsoLogoutAuthorizeResponse: - type: object - properties: - logout_url: - type: string - description: >- - The URL to redirect the user to in order to log out ([Logout - Redirect](/reference/sso/logout) endpoint ready to use). - example: https://auth.workos.com/sso/logout?token=eyJhbGciOiJSUzI1NiJ9 - logout_token: - type: string - description: >- - The logout token to be used in the [Logout - Redirect](/reference/sso/logout) endpoint. - example: >- - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9maWxlX2lkIjoicHJvZl8wMUdXUTFHMEgyRk02QVNFRjBIUzEzSENXOS0zMDRrZzAzZyIsImV4cCI6IjE1MTYyMzkwMjIifQ.Wru9Qlnf5DpohtGCKhZU4cVOd3zpiu7QQ-XEX--5A_4 - required: - - logout_url - - logout_token - JwksResponse: - type: object - properties: - keys: - type: array - items: - type: object - properties: - alg: - type: string - description: Algorithm. - const: RS256 - kty: - type: string - description: Key type. - const: RSA - use: - type: string - description: Key use (signature). - const: sig - x5c: - type: array - items: - type: string - description: X.509 certificate chain. - example: - - MIIDQjCCAiqgAwIBAgIGATz/FuLiMA0GCSqGSIb3DQEBCwUA... - 'n': - type: string - description: RSA modulus. - example: 0vx7agoebGc...eKnNs - e: - type: string - description: RSA exponent. - example: AQAB - kid: - type: string - description: Key ID. - example: key_01HXYZ123456789ABCDEFGHIJ - x5t#S256: - type: string - description: X.509 certificate SHA-256 thumbprint. - example: ZjQzYjI0OT...NmNjU0 - required: - - alg - - kty - - use - - x5c - - 'n' - - e - - kid - - x5t#S256 - description: The public keys used for verifying access tokens. - required: - - keys -security: - - bearer: [] From 5a5ad2b7d54014d8117e7b6bb20447e8011387f2 Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Mon, 4 May 2026 17:26:22 -0700 Subject: [PATCH 05/17] chore(build): remove vendored YAML copy from postbuild The spec is now resolved from @workos/openapi-spec in node_modules at runtime via require.resolve, so the postbuild cp is unnecessary. --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index f20c66e..3ca6109 100644 --- a/package.json +++ b/package.json @@ -94,7 +94,7 @@ "prebuild": "pnpm clean", "build:watch": "pnpm tsc -w", "build": "pnpm tsc", - "postbuild": "chmod +x ./dist/bin.js && cp -r scripts/** dist && cp src/commands/api/workos-openapi-spec.yaml dist/commands/api/", + "postbuild": "chmod +x ./dist/bin.js && cp -r scripts/** dist", "lint": "oxlint", "format": "oxfmt .", "format:check": "oxfmt --check .", From 39c67aa0110b92e903f20b3dce3edb339d43077e Mon Sep 17 00:00:00 2001 From: Nick Nisi Date: Mon, 4 May 2026 17:36:43 -0700 Subject: [PATCH 06/17] refactor(api): address code review findings - Extract colorMethod + printResponse to format.ts (breaks circular import) - Collapse PathParam/QueryParam into single Param type - Simplify endpointsByTag to accept EndpointInfo[] directly - Add assertNotCancelled helper (eliminates 8x cancel+cast boilerplate) - Add network error handling in apiRequest - resolveBody returns undefined instead of null - Remove unnecessary comments --- src/commands/api/catalog.ts | 24 ++-- src/commands/api/format.ts | 40 +++++++ src/commands/api/index.ts | 79 +++---------- src/commands/api/interactive.ts | 192 ++++++++++++++------------------ src/commands/api/request.ts | 19 ++-- 5 files changed, 153 insertions(+), 201 deletions(-) create mode 100644 src/commands/api/format.ts diff --git a/src/commands/api/catalog.ts b/src/commands/api/catalog.ts index 338cad0..f712114 100644 --- a/src/commands/api/catalog.ts +++ b/src/commands/api/catalog.ts @@ -1,18 +1,8 @@ -/** - * OpenAPI catalog: parsing the embedded spec into a queryable endpoint list. - */ - import { parse as parseYaml } from 'yaml'; import { createRequire } from 'node:module'; import { readFileSync } from 'node:fs'; -export interface PathParam { - name: string; - description: string; - required: boolean; -} - -export interface QueryParam { +export interface Param { name: string; description: string; required: boolean; @@ -24,8 +14,8 @@ export interface EndpointInfo { summary: string; tag: string; operationId: string; - pathParams: PathParam[]; - queryParams: QueryParam[]; + pathParams: Param[]; + queryParams: Param[]; hasRequestBody: boolean; } @@ -52,11 +42,11 @@ export function parseSpec(yamlText: string): Catalog { const allParams = [...((pathObj.parameters as unknown[]) ?? []), ...((op.parameters as unknown[]) ?? [])]; - const pathParams: PathParam[] = allParams + const pathParams: Param[] = allParams .filter((p: any) => p.in === 'path') .map((p: any) => ({ name: p.name, description: p.description ?? '', required: p.required ?? true })); - const queryParams: QueryParam[] = allParams + const queryParams: Param[] = allParams .filter((p: any) => p.in === 'query') .map((p: any) => ({ name: p.name, description: p.description ?? '', required: p.required ?? false })); @@ -89,9 +79,9 @@ export function loadCatalog(): Catalog { return cachedCatalog; } -export function endpointsByTag(catalog: Catalog): Map { +export function endpointsByTag(endpoints: EndpointInfo[]): Map { const grouped = new Map(); - for (const ep of catalog.endpoints) { + for (const ep of endpoints) { const list = grouped.get(ep.tag) ?? []; list.push(ep); grouped.set(ep.tag, list); diff --git a/src/commands/api/format.ts b/src/commands/api/format.ts new file mode 100644 index 0000000..e1d0cd0 --- /dev/null +++ b/src/commands/api/format.ts @@ -0,0 +1,40 @@ +import chalk from 'chalk'; +import { isJsonMode, outputJson } from '../../utils/output.js'; +import type { ApiResponse } from './request.js'; + +export function colorMethod(method: string): string { + switch (method) { + case 'GET': + return chalk.green(method); + case 'POST': + return chalk.blue(method); + case 'PUT': + case 'PATCH': + return chalk.yellow(method); + case 'DELETE': + return chalk.red(method); + default: + return method; + } +} + +export function printResponse( + response: ApiResponse, + { includeStatus = false }: { includeStatus?: boolean } = {}, +): void { + if (includeStatus) { + console.log(chalk.dim(`HTTP ${response.status}`)); + response.headers.forEach((value, key) => { + console.log(chalk.dim(`${key}: ${value}`)); + }); + console.log(); + } + + if (isJsonMode()) { + outputJson(response.body); + } else if (typeof response.body === 'object' && response.body !== null) { + console.log(JSON.stringify(response.body, null, 2)); + } else { + console.log(response.rawBody); + } +} diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 928864a..8114e50 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -1,12 +1,3 @@ -/** - * `workos api` — generic authenticated API gateway. - * - * Modes: - * workos api — interactive request builder (TTY only) - * workos api ls [filter] — list endpoints from the embedded OpenAPI spec - * workos api [opts] — make an authenticated request - */ - import chalk from 'chalk'; import { readFileSync } from 'node:fs'; import { loadCatalog, endpointsByTag } from './catalog.js'; @@ -14,6 +5,9 @@ import { apiRequest } from './request.js'; import { resolveApiBaseUrl } from '../../lib/api-key.js'; import { isJsonMode, outputJson } from '../../utils/output.js'; import { isNonInteractiveEnvironment } from '../../utils/environment.js'; +import { colorMethod, printResponse } from './format.js'; + +export { colorMethod } from './format.js'; export interface ApiCommandOptions { method?: string; @@ -27,8 +21,6 @@ export interface ApiCommandOptions { const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']); -// ── interactive ─────────────────────────────────────────────────────── - export async function runApiInteractive(): Promise { if (isNonInteractiveEnvironment()) { console.log( @@ -47,8 +39,6 @@ export async function runApiInteractive(): Promise { await apiInteractive(); } -// ── ls ───────────────────────────────────────────────────────────────── - export function runApiLs(filter?: string): void { const catalog = loadCatalog(); let endpoints = catalog.endpoints; @@ -64,15 +54,6 @@ export function runApiLs(filter?: string): void { ); } - if (endpoints.length === 0) { - if (isJsonMode()) { - outputJson({ data: [] }); - } else { - console.log(filter ? `No endpoints matching "${filter}".` : 'No endpoints found.'); - } - return; - } - if (isJsonMode()) { outputJson({ data: endpoints.map((e) => ({ @@ -85,7 +66,12 @@ export function runApiLs(filter?: string): void { return; } - const grouped = endpointsByTag({ endpoints, tags: [...new Set(endpoints.map((e) => e.tag))].sort() }); + if (endpoints.length === 0) { + console.log(filter ? `No endpoints matching "${filter}".` : 'No endpoints found.'); + return; + } + + const grouped = endpointsByTag(endpoints); for (const [tag, eps] of grouped) { console.log(`\n${chalk.bold(tag)}`); @@ -97,8 +83,6 @@ export function runApiLs(filter?: string): void { console.log(); } -// ── request ──────────────────────────────────────────────────────────── - export async function runApiRequest(endpoint: string, options: ApiCommandOptions): Promise { const body = await resolveBody(options); const method = (options.method ?? (body ? 'POST' : 'GET')).toUpperCase(); @@ -133,35 +117,23 @@ export async function runApiRequest(endpoint: string, options: ApiCommandOptions method, path: normalizePath(endpoint), apiKey: options.apiKey, - body: body ?? undefined, + body, baseUrl, }); - if (options.include) { - printHeaders(response.status, response.headers); - } - - if (isJsonMode()) { - outputJson(response.body); - } else if (typeof response.body === 'object' && response.body !== null) { - console.log(JSON.stringify(response.body, null, 2)); - } else { - console.log(response.rawBody); - } + printResponse(response, { includeStatus: options.include }); if (response.status >= 400) { process.exit(1); } } -// ── helpers ──────────────────────────────────────────────────────────── - function normalizePath(path: string): string { if (!path.startsWith('/')) return `/${path}`; return path; } -async function resolveBody(options: ApiCommandOptions): Promise { +async function resolveBody(options: ApiCommandOptions): Promise { if (options.data) return options.data; if (options.file) { if (options.file === '-') { @@ -173,7 +145,7 @@ async function resolveBody(options: ApiCommandOptions): Promise { } return readFileSync(options.file, 'utf-8'); } - return null; + return undefined; } function prettyPrint(jsonString: string): void { @@ -183,28 +155,3 @@ function prettyPrint(jsonString: string): void { console.log(jsonString); } } - -function printHeaders(status: number, headers: Headers): void { - console.log(chalk.dim(`HTTP ${status}`)); - headers.forEach((value, key) => { - console.log(chalk.dim(`${key}: ${value}`)); - }); - console.log(); -} - -export function colorMethod(method: string): string { - switch (method) { - case 'GET': - return chalk.green(method); - case 'POST': - return chalk.blue(method); - case 'PUT': - return chalk.yellow(method); - case 'PATCH': - return chalk.yellow(method); - case 'DELETE': - return chalk.red(method); - default: - return method; - } -} diff --git a/src/commands/api/interactive.ts b/src/commands/api/interactive.ts index a6180bf..b4ee150 100644 --- a/src/commands/api/interactive.ts +++ b/src/commands/api/interactive.ts @@ -1,89 +1,79 @@ -/** - * Interactive API request builder for `workos api` (no args, TTY only). - * - * Flow: category → endpoint → path params → body → confirm → execute. - */ - -import chalk from 'chalk'; import clack from '../../utils/clack.js'; import { loadCatalog, endpointsByTag, type EndpointInfo } from './catalog.js'; import { apiRequest } from './request.js'; -import { colorMethod } from './index.js'; +import { colorMethod, printResponse } from './format.js'; import { resolveApiKey, resolveApiBaseUrl } from '../../lib/api-key.js'; -import { isJsonMode, outputJson } from '../../utils/output.js'; + +function assertNotCancelled(value: T | symbol): T { + if (clack.isCancel(value)) process.exit(0); + return value as T; +} export async function apiInteractive(): Promise { const catalog = loadCatalog(); - const grouped = endpointsByTag(catalog); - - // 1. Select category - const tag = await clack.select({ - message: 'Select a category:', - options: catalog.tags.map((t) => { - const count = grouped.get(t)?.length ?? 0; - return { value: t, label: `${t} (${count})` }; + const grouped = endpointsByTag(catalog.endpoints); + + const tag = assertNotCancelled( + await clack.select({ + message: 'Select a category:', + options: catalog.tags.map((t) => { + const count = grouped.get(t)?.length ?? 0; + return { value: t, label: `${t} (${count})` }; + }), }), - }); - - if (clack.isCancel(tag)) process.exit(0); - - // 2. Select endpoint - const endpoints = grouped.get(tag as string)!; - const endpoint = await clack.select({ - message: 'Select an endpoint:', - options: endpoints.map((e) => ({ - value: e, - label: `${colorMethod(e.method).padEnd(18)} ${e.path}`, - hint: e.summary, - })), - }); - - if (clack.isCancel(endpoint)) process.exit(0); - - const ep = endpoint as EndpointInfo; + ); + + const endpoints = grouped.get(tag)!; + const ep = assertNotCancelled( + await clack.select({ + message: 'Select an endpoint:', + options: endpoints.map((e) => ({ + value: e, + label: `${colorMethod(e.method).padEnd(18)} ${e.path}`, + hint: e.summary, + })), + }), + ); - // 3. Fill path parameters let resolvedPath = ep.path; for (const param of ep.pathParams) { - const hint = param.description || undefined; - const value = await clack.text({ - message: `${param.name}:`, - placeholder: hint, - validate: (v) => { - if (!v?.trim()) return `${param.name} is required`; - }, - }); - - if (clack.isCancel(value)) process.exit(0); - resolvedPath = resolvedPath.replace(`{${param.name}}`, (value as string).trim()); + const value = assertNotCancelled( + await clack.text({ + message: `${param.name}:`, + placeholder: param.description || undefined, + validate: (v) => { + if (!v?.trim()) return `${param.name} is required`; + }, + }), + ); + resolvedPath = resolvedPath.replace(`{${param.name}}`, value.trim()); } - // 4. Query parameters (optional) let queryString = ''; if (ep.queryParams.length > 0) { - const wantsQuery = await clack.confirm({ - message: `Add query parameters? (${ep.queryParams.length} available)`, - initialValue: false, - }); - - if (clack.isCancel(wantsQuery)) process.exit(0); + const wantsQuery = assertNotCancelled( + await clack.confirm({ + message: `Add query parameters? (${ep.queryParams.length} available)`, + initialValue: false, + }), + ); if (wantsQuery) { const params: string[] = []; for (const qp of ep.queryParams) { const label = qp.required ? `${qp.name} (required):` : `${qp.name}:`; - const value = await clack.text({ - message: label, - placeholder: qp.description || undefined, - validate: qp.required - ? (v) => { - if (!v?.trim()) return `${qp.name} is required`; - } - : undefined, - }); - - if (clack.isCancel(value)) process.exit(0); - const trimmed = (value as string).trim(); + const value = assertNotCancelled( + await clack.text({ + message: label, + placeholder: qp.description || undefined, + validate: qp.required + ? (v) => { + if (!v?.trim()) return `${qp.name} is required`; + } + : undefined, + }), + ); + const trimmed = value.trim(); if (trimmed) { params.push(`${encodeURIComponent(qp.name)}=${encodeURIComponent(trimmed)}`); } @@ -94,69 +84,53 @@ export async function apiInteractive(): Promise { } } - // 5. Request body let body: string | undefined; if (ep.hasRequestBody) { - const wantsBody = await clack.confirm({ - message: 'Provide a request body?', - initialValue: ep.method === 'POST' || ep.method === 'PUT', - }); - - if (clack.isCancel(wantsBody)) process.exit(0); + const wantsBody = assertNotCancelled( + await clack.confirm({ + message: 'Provide a request body?', + initialValue: ep.method === 'POST' || ep.method === 'PUT', + }), + ); if (wantsBody) { - const bodyText = await clack.text({ - message: 'Request body (JSON):', - placeholder: '{"key": "value"}', - validate: (v) => { - if (!v?.trim()) return 'Body cannot be empty'; - try { - JSON.parse(v); - } catch { - return 'Invalid JSON'; - } - }, - }); - - if (clack.isCancel(bodyText)) process.exit(0); - body = (bodyText as string).trim(); + body = assertNotCancelled( + await clack.text({ + message: 'Request body (JSON):', + placeholder: '{"key": "value"}', + validate: (v) => { + if (!v?.trim()) return 'Body cannot be empty'; + try { + JSON.parse(v); + } catch { + return 'Invalid JSON'; + } + }, + }), + ).trim(); } } const fullPath = `${resolvedPath}${queryString}`; - // 6. Confirm - console.log(); - console.log(` ${colorMethod(ep.method)} ${fullPath}`); + console.log(`\n ${colorMethod(ep.method)} ${fullPath}`); if (body) { - console.log(chalk.dim(JSON.stringify(JSON.parse(body), null, 2))); + console.log(JSON.stringify(JSON.parse(body), null, 2)); } console.log(); - const ok = await clack.confirm({ message: 'Execute this request?' }); - if (clack.isCancel(ok) || !ok) process.exit(0); - - // 7. Execute - const apiKey = resolveApiKey(); - const baseUrl = resolveApiBaseUrl(); + const ok = assertNotCancelled(await clack.confirm({ message: 'Execute this request?' })); + if (!ok) process.exit(0); const response = await apiRequest({ method: ep.method, path: fullPath, - apiKey, - baseUrl, + apiKey: resolveApiKey(), + baseUrl: resolveApiBaseUrl(), body, }); - console.log(chalk.dim(`\nHTTP ${response.status}`)); - - if (isJsonMode()) { - outputJson(response.body); - } else if (typeof response.body === 'object' && response.body !== null) { - console.log(JSON.stringify(response.body, null, 2)); - } else { - console.log(response.rawBody); - } + printResponse(response, { includeStatus: true }); if (response.status >= 400) { process.exit(1); diff --git a/src/commands/api/request.ts b/src/commands/api/request.ts index 79589a5..53799f4 100644 --- a/src/commands/api/request.ts +++ b/src/commands/api/request.ts @@ -1,7 +1,3 @@ -/** - * Raw API request executor for `workos api `. - */ - import { resolveApiKey, resolveApiBaseUrl } from '../../lib/api-key.js'; export interface ApiRequestOptions { @@ -37,11 +33,16 @@ export async function apiRequest(options: ApiRequestOptions): Promise Date: Tue, 5 May 2026 21:26:58 +0000 Subject: [PATCH 07/17] fix(api): handle invalid JSON body in dry-run JSON mode and add tests - Catch JSON.parse errors in --dry-run --json path and exit with a structured error instead of crashing with an unhandled SyntaxError - Add spec coverage for the new src/commands/api/* files (catalog, format, request, index) including JSON mode behavior Addresses Devin Review findings on PR #142. --- src/commands/api/catalog.spec.ts | 162 +++++++++++++++++ src/commands/api/format.spec.ts | 109 +++++++++++ src/commands/api/index.spec.ts | 300 +++++++++++++++++++++++++++++++ src/commands/api/index.ts | 12 +- src/commands/api/request.spec.ts | 113 ++++++++++++ 5 files changed, 694 insertions(+), 2 deletions(-) create mode 100644 src/commands/api/catalog.spec.ts create mode 100644 src/commands/api/format.spec.ts create mode 100644 src/commands/api/index.spec.ts create mode 100644 src/commands/api/request.spec.ts diff --git a/src/commands/api/catalog.spec.ts b/src/commands/api/catalog.spec.ts new file mode 100644 index 0000000..a0b11d8 --- /dev/null +++ b/src/commands/api/catalog.spec.ts @@ -0,0 +1,162 @@ +import { describe, it, expect } from 'vitest'; +import { parseSpec, endpointsByTag, type EndpointInfo } from './catalog.js'; + +const SAMPLE_SPEC = ` +openapi: 3.0.0 +info: + title: Test + version: 1.0.0 +paths: + /organizations: + get: + operationId: listOrganizations + summary: List organizations + tags: [Organizations] + parameters: + - name: limit + in: query + required: false + description: Max items + post: + operationId: createOrganization + summary: Create organization + tags: [Organizations] + requestBody: + required: true + content: + application/json: + schema: + type: object + /organizations/{id}: + parameters: + - name: id + in: path + required: true + description: Organization id + get: + operationId: getOrganization + summary: Get organization + tags: [Organizations] + delete: + operationId: deleteOrganization + summary: Delete organization + tags: [Organizations] + /users: + get: + operationId: listUsers + summary: List users + tags: [Users] +`; + +describe('parseSpec', () => { + it('returns endpoints for each method on a path', () => { + const catalog = parseSpec(SAMPLE_SPEC); + const ops = catalog.endpoints.filter((e) => e.path === '/organizations').map((e) => e.method); + expect(ops.sort()).toEqual(['GET', 'POST']); + }); + + it('captures summary, tag, and operationId', () => { + const catalog = parseSpec(SAMPLE_SPEC); + const get = catalog.endpoints.find((e) => e.path === '/organizations' && e.method === 'GET'); + expect(get).toMatchObject({ + summary: 'List organizations', + tag: 'Organizations', + operationId: 'listOrganizations', + }); + }); + + it('extracts path parameters from shared parameters block', () => { + const catalog = parseSpec(SAMPLE_SPEC); + const get = catalog.endpoints.find((e) => e.path === '/organizations/{id}' && e.method === 'GET'); + expect(get?.pathParams).toEqual([{ name: 'id', description: 'Organization id', required: true }]); + expect(get?.queryParams).toEqual([]); + }); + + it('extracts query parameters from operation', () => { + const catalog = parseSpec(SAMPLE_SPEC); + const get = catalog.endpoints.find((e) => e.path === '/organizations' && e.method === 'GET'); + expect(get?.queryParams).toEqual([{ name: 'limit', description: 'Max items', required: false }]); + }); + + it('flags hasRequestBody when requestBody is present', () => { + const catalog = parseSpec(SAMPLE_SPEC); + const post = catalog.endpoints.find((e) => e.path === '/organizations' && e.method === 'POST'); + const get = catalog.endpoints.find((e) => e.path === '/organizations' && e.method === 'GET'); + expect(post?.hasRequestBody).toBe(true); + expect(get?.hasRequestBody).toBe(false); + }); + + it('produces a sorted unique tags list', () => { + const catalog = parseSpec(SAMPLE_SPEC); + expect(catalog.tags).toEqual(['Organizations', 'Users']); + }); + + it('returns an empty catalog when paths is missing', () => { + const catalog = parseSpec('openapi: 3.0.0\ninfo:\n title: t\n version: 1.0.0\n'); + expect(catalog.endpoints).toEqual([]); + expect(catalog.tags).toEqual([]); + }); + + it('falls back to "other" tag when none is provided', () => { + const yaml = ` +openapi: 3.0.0 +info: + title: Test + version: 1.0.0 +paths: + /noop: + get: + operationId: noop + summary: No tag +`; + const catalog = parseSpec(yaml); + expect(catalog.endpoints[0]?.tag).toBe('other'); + expect(catalog.tags).toEqual(['other']); + }); +}); + +describe('endpointsByTag', () => { + const endpoints: EndpointInfo[] = [ + { + method: 'GET', + path: '/users', + summary: '', + tag: 'Users', + operationId: 'listUsers', + pathParams: [], + queryParams: [], + hasRequestBody: false, + }, + { + method: 'POST', + path: '/organizations', + summary: '', + tag: 'Organizations', + operationId: 'createOrg', + pathParams: [], + queryParams: [], + hasRequestBody: true, + }, + { + method: 'DELETE', + path: '/users/{id}', + summary: '', + tag: 'Users', + operationId: 'deleteUser', + pathParams: [], + queryParams: [], + hasRequestBody: false, + }, + ]; + + it('groups endpoints by tag preserving insertion order', () => { + const grouped = endpointsByTag(endpoints); + expect([...grouped.keys()]).toEqual(['Users', 'Organizations']); + expect(grouped.get('Users')?.map((e) => e.operationId)).toEqual(['listUsers', 'deleteUser']); + expect(grouped.get('Organizations')?.map((e) => e.operationId)).toEqual(['createOrg']); + }); + + it('returns an empty map when no endpoints are provided', () => { + expect(endpointsByTag([]).size).toBe(0); + }); +}); diff --git a/src/commands/api/format.spec.ts b/src/commands/api/format.spec.ts new file mode 100644 index 0000000..37fa2b2 --- /dev/null +++ b/src/commands/api/format.spec.ts @@ -0,0 +1,109 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import chalk from 'chalk'; +import { colorMethod, printResponse } from './format.js'; +import { setOutputMode } from '../../utils/output.js'; +import type { ApiResponse } from './request.js'; + +const previousChalkLevel = chalk.level; + +function buildResponse(overrides: Partial = {}): ApiResponse { + const headers = new Headers(); + headers.set('content-type', 'application/json'); + return { + status: 200, + headers, + body: { ok: true }, + rawBody: '{"ok":true}', + ...overrides, + }; +} + +describe('colorMethod', () => { + beforeEach(() => { + chalk.level = 1; + }); + + afterEach(() => { + chalk.level = previousChalkLevel; + }); + + it('returns the method string regardless of color level', () => { + chalk.level = 0; + expect(colorMethod('GET')).toBe('GET'); + expect(colorMethod('POST')).toBe('POST'); + expect(colorMethod('PUT')).toBe('PUT'); + expect(colorMethod('PATCH')).toBe('PATCH'); + expect(colorMethod('DELETE')).toBe('DELETE'); + expect(colorMethod('OPTIONS')).toBe('OPTIONS'); + }); + + it('matches chalk color helpers when colors are enabled', () => { + expect(colorMethod('GET')).toBe(chalk.green('GET')); + expect(colorMethod('POST')).toBe(chalk.blue('POST')); + expect(colorMethod('PUT')).toBe(chalk.yellow('PUT')); + expect(colorMethod('PATCH')).toBe(chalk.yellow('PATCH')); + expect(colorMethod('DELETE')).toBe(chalk.red('DELETE')); + }); + + it('passes through unknown verbs unchanged', () => { + expect(colorMethod('TRACE')).toBe('TRACE'); + }); +}); + +describe('printResponse', () => { + let consoleOutput: string[]; + + beforeEach(() => { + consoleOutput = []; + vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { + consoleOutput.push(args.map(String).join(' ')); + }); + }); + + afterEach(() => { + vi.restoreAllMocks(); + setOutputMode('human'); + }); + + it('prints a pretty JSON body in human mode', () => { + setOutputMode('human'); + printResponse(buildResponse({ body: { ok: true, count: 2 } })); + expect(consoleOutput.some((l) => l.includes('"ok": true'))).toBe(true); + expect(consoleOutput.some((l) => l.includes('"count": 2'))).toBe(true); + }); + + it('prints raw body when human mode receives a non-object body', () => { + setOutputMode('human'); + printResponse(buildResponse({ body: 'plain text', rawBody: 'plain text' })); + expect(consoleOutput).toContain('plain text'); + }); + + it('prints status and headers when includeStatus is true in human mode', () => { + setOutputMode('human'); + const headers = new Headers({ 'x-request-id': 'abc' }); + printResponse(buildResponse({ status: 201, headers }), { includeStatus: true }); + const joined = consoleOutput.join('\n'); + expect(joined).toContain('HTTP 201'); + expect(joined).toContain('x-request-id: abc'); + }); + + it('emits a single JSON line in JSON mode', () => { + setOutputMode('json'); + printResponse(buildResponse({ body: { ok: true } })); + expect(consoleOutput).toEqual([JSON.stringify({ ok: true })]); + }); + + it('emits the JSON body on stdout in JSON mode regardless of includeStatus', () => { + setOutputMode('json'); + const headers = new Headers({ 'x-request-id': 'abc' }); + printResponse(buildResponse({ status: 201, headers, body: { ok: true } }), { includeStatus: true }); + const jsonLine = consoleOutput.find((line) => { + try { + return JSON.parse(line)?.ok === true; + } catch { + return false; + } + }); + expect(jsonLine).toBe(JSON.stringify({ ok: true })); + }); +}); diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts new file mode 100644 index 0000000..77f3096 --- /dev/null +++ b/src/commands/api/index.spec.ts @@ -0,0 +1,300 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import type { Catalog } from './catalog.js'; +import type { ApiResponse } from './request.js'; + +const mockCatalog: Catalog = { + endpoints: [ + { + method: 'GET', + path: '/users', + summary: 'List users', + tag: 'Users', + operationId: 'listUsers', + pathParams: [], + queryParams: [], + hasRequestBody: false, + }, + { + method: 'POST', + path: '/organizations', + summary: 'Create organization', + tag: 'Organizations', + operationId: 'createOrganization', + pathParams: [], + queryParams: [], + hasRequestBody: true, + }, + { + method: 'DELETE', + path: '/users/{id}', + summary: 'Delete user', + tag: 'Users', + operationId: 'deleteUser', + pathParams: [{ name: 'id', description: '', required: true }], + queryParams: [], + hasRequestBody: false, + }, + ], + tags: ['Organizations', 'Users'], +}; + +const mockApiRequest = vi.fn<(...args: unknown[]) => Promise>(); + +vi.mock('./catalog.js', async () => { + const actual = await vi.importActual('./catalog.js'); + return { + ...actual, + loadCatalog: () => mockCatalog, + }; +}); + +vi.mock('./request.js', () => ({ + apiRequest: (...args: unknown[]) => mockApiRequest(...args), +})); + +vi.mock('../../lib/api-key.js', () => ({ + resolveApiKey: vi.fn(() => 'sk_test'), + resolveApiBaseUrl: vi.fn(() => 'https://api.example.com'), +})); + +const mockConfirm = vi.fn(); +const mockIsCancel = vi.fn(() => false); +vi.mock('../../utils/clack.js', () => ({ + default: { + confirm: (...args: unknown[]) => mockConfirm(...args), + isCancel: (...args: unknown[]) => mockIsCancel(...args), + }, +})); + +vi.mock('../../utils/environment.js', () => ({ + isNonInteractiveEnvironment: vi.fn(() => false), +})); + +const { setOutputMode } = await import('../../utils/output.js'); +const { isNonInteractiveEnvironment } = await import('../../utils/environment.js'); +const { runApiInteractive, runApiLs, runApiRequest } = await import('./index.js'); + +function buildResponse(overrides: Partial = {}): ApiResponse { + return { + status: 200, + headers: new Headers(), + body: { ok: true }, + rawBody: '{"ok":true}', + ...overrides, + }; +} + +describe('runApiInteractive', () => { + let consoleOutput: string[]; + + beforeEach(() => { + vi.clearAllMocks(); + consoleOutput = []; + vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { + consoleOutput.push(args.map(String).join(' ')); + }); + }); + + afterEach(() => { + vi.restoreAllMocks(); + setOutputMode('human'); + }); + + it('prints usage instructions when stdin/stdout is non-interactive', async () => { + vi.mocked(isNonInteractiveEnvironment).mockReturnValueOnce(true); + await runApiInteractive(); + expect(consoleOutput.join('\n')).toContain('Interactive mode requires a TTY'); + }); +}); + +describe('runApiLs', () => { + let consoleOutput: string[]; + + beforeEach(() => { + vi.clearAllMocks(); + consoleOutput = []; + vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { + consoleOutput.push(args.map(String).join(' ')); + }); + }); + + afterEach(() => { + vi.restoreAllMocks(); + setOutputMode('human'); + }); + + it('lists endpoints grouped by tag in human mode', () => { + setOutputMode('human'); + runApiLs(); + const joined = consoleOutput.join('\n'); + expect(joined).toContain('Users'); + expect(joined).toContain('/users'); + expect(joined).toContain('Organizations'); + expect(joined).toContain('/organizations'); + }); + + it('filters endpoints by substring (path/tag/summary/operationId)', () => { + setOutputMode('human'); + runApiLs('organization'); + const joined = consoleOutput.join('\n'); + expect(joined).toContain('/organizations'); + expect(joined).not.toContain('/users'); + }); + + it('prints a friendly message when no endpoint matches the filter', () => { + setOutputMode('human'); + runApiLs('does-not-exist'); + expect(consoleOutput.some((l) => l.includes('No endpoints matching "does-not-exist"'))).toBe(true); + }); + + it('emits structured JSON in JSON mode', () => { + setOutputMode('json'); + runApiLs('users'); + expect(consoleOutput).toHaveLength(1); + const parsed = JSON.parse(consoleOutput[0]!); + expect(parsed.data).toEqual([ + { method: 'GET', path: '/users', summary: 'List users', tag: 'Users' }, + { method: 'DELETE', path: '/users/{id}', summary: 'Delete user', tag: 'Users' }, + ]); + }); +}); + +describe('runApiRequest', () => { + let consoleOutput: string[]; + let stderrOutput: string[]; + let exitSpy: ReturnType; + + beforeEach(() => { + vi.clearAllMocks(); + consoleOutput = []; + stderrOutput = []; + vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { + consoleOutput.push(args.map(String).join(' ')); + }); + vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => { + stderrOutput.push(args.map(String).join(' ')); + }); + exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => { + throw new Error(`__exit__:${code ?? 0}`); + }) as never); + mockConfirm.mockResolvedValue(true); + mockIsCancel.mockReturnValue(false); + }); + + afterEach(() => { + vi.restoreAllMocks(); + setOutputMode('human'); + }); + + it('prints a human-readable dry-run preview without executing the request', async () => { + setOutputMode('human'); + await runApiRequest('/users', { dryRun: true }); + expect(mockApiRequest).not.toHaveBeenCalled(); + const joined = consoleOutput.join('\n'); + expect(joined).toContain('[dry-run]'); + expect(joined).toContain('GET https://api.example.com/users'); + }); + + it('emits structured JSON for a dry-run in JSON mode', async () => { + setOutputMode('json'); + await runApiRequest('/users', { dryRun: true }); + expect(mockApiRequest).not.toHaveBeenCalled(); + const parsed = JSON.parse(consoleOutput[0]!); + expect(parsed).toEqual({ + dryRun: true, + method: 'GET', + url: 'https://api.example.com/users', + }); + }); + + it('parses --data into the JSON dry-run payload', async () => { + setOutputMode('json'); + await runApiRequest('/organizations', { dryRun: true, data: '{"name":"Acme"}' }); + const parsed = JSON.parse(consoleOutput[0]!); + expect(parsed).toEqual({ + dryRun: true, + method: 'POST', + url: 'https://api.example.com/organizations', + body: { name: 'Acme' }, + }); + }); + + it('exits with a structured error in JSON dry-run mode when --data is not valid JSON', async () => { + setOutputMode('json'); + await expect( + runApiRequest('/organizations', { dryRun: true, data: 'not json' }), + ).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + const errorLine = stderrOutput.find((line) => { + try { + const parsed = JSON.parse(line); + return parsed?.error?.code === 'invalid_json_body'; + } catch { + return false; + } + }); + expect(errorLine).toBeDefined(); + }); + + it('falls back to a raw human-mode preview when --data is not valid JSON', async () => { + setOutputMode('human'); + await runApiRequest('/organizations', { dryRun: true, data: 'not json' }); + expect(mockApiRequest).not.toHaveBeenCalled(); + const joined = consoleOutput.join('\n'); + expect(joined).toContain('[dry-run]'); + expect(joined).toContain('not json'); + }); + + it('infers POST when a body is provided without an explicit method', async () => { + mockApiRequest.mockResolvedValue(buildResponse()); + await runApiRequest('/organizations', { data: '{"name":"Acme"}', yes: true }); + expect(mockApiRequest).toHaveBeenCalledWith( + expect.objectContaining({ method: 'POST', path: '/organizations', body: '{"name":"Acme"}' }), + ); + }); + + it('skips confirmation when --yes is set for mutating methods', async () => { + mockApiRequest.mockResolvedValue(buildResponse()); + await runApiRequest('/organizations', { method: 'DELETE', yes: true }); + expect(mockConfirm).not.toHaveBeenCalled(); + expect(mockApiRequest).toHaveBeenCalled(); + }); + + it('prompts for confirmation on mutating methods in TTY environments', async () => { + mockApiRequest.mockResolvedValue(buildResponse()); + mockConfirm.mockResolvedValueOnce(true); + await runApiRequest('/organizations', { method: 'POST', data: '{}' }); + expect(mockConfirm).toHaveBeenCalled(); + expect(mockApiRequest).toHaveBeenCalled(); + }); + + it('aborts when the user declines the confirmation prompt', async () => { + mockConfirm.mockResolvedValueOnce(false); + await expect(runApiRequest('/organizations', { method: 'POST', data: '{}' })).rejects.toThrow( + /__exit__:0/, + ); + expect(mockApiRequest).not.toHaveBeenCalled(); + }); + + it('exits with code 1 when the response status is >= 400', async () => { + mockApiRequest.mockResolvedValue(buildResponse({ status: 404, body: { error: 'not_found' } })); + await expect(runApiRequest('/users', { yes: true })).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + }); + + it('passes --include through to printResponse', async () => { + setOutputMode('human'); + const headers = new Headers({ 'x-request-id': 'abc' }); + mockApiRequest.mockResolvedValue(buildResponse({ status: 201, headers })); + await runApiRequest('/users', { include: true, yes: true }); + const joined = consoleOutput.join('\n'); + expect(joined).toContain('HTTP 201'); + expect(joined).toContain('x-request-id: abc'); + }); + + it('forwards --api-key to apiRequest', async () => { + mockApiRequest.mockResolvedValue(buildResponse()); + await runApiRequest('/users', { apiKey: 'sk_override', yes: true }); + expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ apiKey: 'sk_override' })); + }); +}); diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 8114e50..1bf044e 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs'; import { loadCatalog, endpointsByTag } from './catalog.js'; import { apiRequest } from './request.js'; import { resolveApiBaseUrl } from '../../lib/api-key.js'; -import { isJsonMode, outputJson } from '../../utils/output.js'; +import { exitWithError, isJsonMode, outputJson } from '../../utils/output.js'; import { isNonInteractiveEnvironment } from '../../utils/environment.js'; import { colorMethod, printResponse } from './format.js'; @@ -90,11 +90,19 @@ export async function runApiRequest(endpoint: string, options: ApiCommandOptions if (options.dryRun) { if (isJsonMode()) { + let parsedBody: unknown; + if (body) { + try { + parsedBody = JSON.parse(body); + } catch { + exitWithError({ code: 'invalid_json_body', message: 'Request body is not valid JSON.' }); + } + } outputJson({ dryRun: true, method, url: `${baseUrl}${normalizePath(endpoint)}`, - body: body ? JSON.parse(body) : undefined, + body: parsedBody, }); } else { console.log(`${chalk.dim('[dry-run]')} ${method} ${baseUrl}${normalizePath(endpoint)}`); diff --git a/src/commands/api/request.spec.ts b/src/commands/api/request.spec.ts new file mode 100644 index 0000000..a3e0693 --- /dev/null +++ b/src/commands/api/request.spec.ts @@ -0,0 +1,113 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; + +vi.mock('../../lib/api-key.js', () => ({ + resolveApiKey: vi.fn(() => 'sk_test_default'), + resolveApiBaseUrl: vi.fn(() => 'https://api.example.com'), +})); + +const { apiRequest } = await import('./request.js'); +const { resolveApiKey, resolveApiBaseUrl } = await import('../../lib/api-key.js'); + +function buildResponse(body: string, init: ResponseInit = {}): Response { + return new Response(body, init); +} + +describe('apiRequest', () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('uses provided apiKey and baseUrl over resolver fallbacks', async () => { + const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{"ok":true}')); + await apiRequest({ + method: 'GET', + path: '/users', + apiKey: 'sk_explicit', + baseUrl: 'https://override.example.com', + }); + expect(fetchSpy).toHaveBeenCalledWith( + 'https://override.example.com/users', + expect.objectContaining({ + method: 'GET', + headers: expect.objectContaining({ + Authorization: 'Bearer sk_explicit', + Accept: 'application/json', + }), + }), + ); + expect(resolveApiKey).not.toHaveBeenCalled(); + expect(resolveApiBaseUrl).not.toHaveBeenCalled(); + }); + + it('falls back to resolveApiKey and resolveApiBaseUrl when not provided', async () => { + const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{}')); + await apiRequest({ method: 'GET', path: '/users' }); + expect(resolveApiKey).toHaveBeenCalled(); + expect(resolveApiBaseUrl).toHaveBeenCalled(); + expect(fetchSpy).toHaveBeenCalledWith( + 'https://api.example.com/users', + expect.objectContaining({ + headers: expect.objectContaining({ Authorization: 'Bearer sk_test_default' }), + }), + ); + }); + + it('prefixes path with a leading slash when missing', async () => { + const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{}')); + await apiRequest({ method: 'GET', path: 'users' }); + expect(fetchSpy).toHaveBeenCalledWith('https://api.example.com/users', expect.any(Object)); + }); + + it('sends body and Content-Type when body is provided', async () => { + const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{}')); + await apiRequest({ method: 'POST', path: '/orgs', body: '{"name":"Acme"}' }); + const init = fetchSpy.mock.calls[0]![1]!; + const headers = init.headers as Record; + expect(init.method).toBe('POST'); + expect(init.body).toBe('{"name":"Acme"}'); + expect(headers['Content-Type']).toBe('application/json'); + }); + + it('omits Content-Type when no body is provided', async () => { + const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{}')); + await apiRequest({ method: 'GET', path: '/orgs' }); + const init = fetchSpy.mock.calls[0]![1]!; + const headers = init.headers as Record; + expect(headers['Content-Type']).toBeUndefined(); + }); + + it('parses a JSON response body', async () => { + vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{"id":"org_123"}', { status: 200 })); + const response = await apiRequest({ method: 'GET', path: '/orgs/org_123' }); + expect(response.status).toBe(200); + expect(response.body).toEqual({ id: 'org_123' }); + expect(response.rawBody).toBe('{"id":"org_123"}'); + }); + + it('returns the raw string when response body is not JSON', async () => { + vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('plain text', { status: 200 })); + const response = await apiRequest({ method: 'GET', path: '/health' }); + expect(response.body).toBe('plain text'); + expect(response.rawBody).toBe('plain text'); + }); + + it('preserves non-2xx status codes for the caller to inspect', async () => { + vi.spyOn(global, 'fetch').mockResolvedValue( + buildResponse('{"error":"unauthorized"}', { status: 401 }), + ); + const response = await apiRequest({ method: 'GET', path: '/orgs' }); + expect(response.status).toBe(401); + expect(response.body).toEqual({ error: 'unauthorized' }); + }); + + it('throws a friendly error when the network request fails', async () => { + vi.spyOn(global, 'fetch').mockRejectedValue(new Error('ECONNREFUSED')); + await expect(apiRequest({ method: 'GET', path: '/orgs' })).rejects.toThrow( + /Failed to connect to WorkOS API/, + ); + }); +}); From aaaa66f59f211eedfdd3c4d14e82553a203ca426 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 21:35:17 +0000 Subject: [PATCH 08/17] fix(api): emit pure JSON in JSON mode and gracefully handle missing --file - printResponse now produces a single structured JSON object on stdout in JSON mode (including status and headers when --include is set), instead of leaking human-readable status/header lines that would corrupt machine-readable output. - resolveBody now uses async readFile and surfaces missing files via exitWithError(file_read_error) instead of throwing a raw ENOENT stack trace. - Update format.spec.ts to assert pure-JSON output in JSON mode and add a regression test for the missing --file path. Co-Authored-By: nick.nisi@workos.com --- src/commands/api/format.spec.ts | 31 ++++++++++++++++++++++--------- src/commands/api/format.ts | 17 ++++++++++++++--- src/commands/api/index.spec.ts | 26 ++++++++++++++++++++------ src/commands/api/index.ts | 12 ++++++++++-- src/commands/api/request.spec.ts | 8 ++------ 5 files changed, 68 insertions(+), 26 deletions(-) diff --git a/src/commands/api/format.spec.ts b/src/commands/api/format.spec.ts index 37fa2b2..aff627b 100644 --- a/src/commands/api/format.spec.ts +++ b/src/commands/api/format.spec.ts @@ -93,17 +93,30 @@ describe('printResponse', () => { expect(consoleOutput).toEqual([JSON.stringify({ ok: true })]); }); - it('emits the JSON body on stdout in JSON mode regardless of includeStatus', () => { + it('emits a single structured JSON line in JSON mode when includeStatus is true', () => { setOutputMode('json'); const headers = new Headers({ 'x-request-id': 'abc' }); printResponse(buildResponse({ status: 201, headers, body: { ok: true } }), { includeStatus: true }); - const jsonLine = consoleOutput.find((line) => { - try { - return JSON.parse(line)?.ok === true; - } catch { - return false; - } - }); - expect(jsonLine).toBe(JSON.stringify({ ok: true })); + + expect(consoleOutput).toHaveLength(1); + const parsed = JSON.parse(consoleOutput[0]!) as { + status: number; + headers: Record; + body: { ok: boolean }; + }; + expect(parsed.status).toBe(201); + expect(parsed.headers['x-request-id']).toBe('abc'); + expect(parsed.body).toEqual({ ok: true }); + }); + + it('does not emit any human-readable status/header lines in JSON mode', () => { + setOutputMode('json'); + const headers = new Headers({ 'x-request-id': 'abc' }); + printResponse(buildResponse({ status: 201, headers, body: { ok: true } }), { includeStatus: true }); + + for (const line of consoleOutput) { + expect(line).not.toMatch(/^HTTP \d/); + expect(line).not.toMatch(/^x-request-id:/); + } }); }); diff --git a/src/commands/api/format.ts b/src/commands/api/format.ts index e1d0cd0..5f76041 100644 --- a/src/commands/api/format.ts +++ b/src/commands/api/format.ts @@ -22,6 +22,19 @@ export function printResponse( response: ApiResponse, { includeStatus = false }: { includeStatus?: boolean } = {}, ): void { + if (isJsonMode()) { + if (includeStatus) { + const headers: Record = {}; + response.headers.forEach((value, key) => { + headers[key] = value; + }); + outputJson({ status: response.status, headers, body: response.body }); + } else { + outputJson(response.body); + } + return; + } + if (includeStatus) { console.log(chalk.dim(`HTTP ${response.status}`)); response.headers.forEach((value, key) => { @@ -30,9 +43,7 @@ export function printResponse( console.log(); } - if (isJsonMode()) { - outputJson(response.body); - } else if (typeof response.body === 'object' && response.body !== null) { + if (typeof response.body === 'object' && response.body !== null) { console.log(JSON.stringify(response.body, null, 2)); } else { console.log(response.rawBody); diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index 77f3096..ebd34c4 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -221,9 +221,7 @@ describe('runApiRequest', () => { it('exits with a structured error in JSON dry-run mode when --data is not valid JSON', async () => { setOutputMode('json'); - await expect( - runApiRequest('/organizations', { dryRun: true, data: 'not json' }), - ).rejects.toThrow(/__exit__:1/); + await expect(runApiRequest('/organizations', { dryRun: true, data: 'not json' })).rejects.toThrow(/__exit__:1/); expect(exitSpy).toHaveBeenCalledWith(1); const errorLine = stderrOutput.find((line) => { try { @@ -270,9 +268,7 @@ describe('runApiRequest', () => { it('aborts when the user declines the confirmation prompt', async () => { mockConfirm.mockResolvedValueOnce(false); - await expect(runApiRequest('/organizations', { method: 'POST', data: '{}' })).rejects.toThrow( - /__exit__:0/, - ); + await expect(runApiRequest('/organizations', { method: 'POST', data: '{}' })).rejects.toThrow(/__exit__:0/); expect(mockApiRequest).not.toHaveBeenCalled(); }); @@ -297,4 +293,22 @@ describe('runApiRequest', () => { await runApiRequest('/users', { apiKey: 'sk_override', yes: true }); expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ apiKey: 'sk_override' })); }); + + it('exits with a structured error when --file points at a missing path', async () => { + setOutputMode('json'); + await expect( + runApiRequest('/organizations', { file: '/tmp/__nonexistent_workos_api_body__.json', yes: true }), + ).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + const errorLine = stderrOutput.find((line) => { + try { + const parsed = JSON.parse(line) as { error?: { code?: string; message?: string } }; + return parsed.error?.code === 'file_read_error'; + } catch { + return false; + } + }); + expect(errorLine).toBeDefined(); + expect(mockApiRequest).not.toHaveBeenCalled(); + }); }); diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 1bf044e..0f02b6e 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -1,5 +1,5 @@ import chalk from 'chalk'; -import { readFileSync } from 'node:fs'; +import { readFile } from 'node:fs/promises'; import { loadCatalog, endpointsByTag } from './catalog.js'; import { apiRequest } from './request.js'; import { resolveApiBaseUrl } from '../../lib/api-key.js'; @@ -151,7 +151,15 @@ async function resolveBody(options: ApiCommandOptions): Promise { }); it('preserves non-2xx status codes for the caller to inspect', async () => { - vi.spyOn(global, 'fetch').mockResolvedValue( - buildResponse('{"error":"unauthorized"}', { status: 401 }), - ); + vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{"error":"unauthorized"}', { status: 401 })); const response = await apiRequest({ method: 'GET', path: '/orgs' }); expect(response.status).toBe(401); expect(response.body).toEqual({ error: 'unauthorized' }); @@ -106,8 +104,6 @@ describe('apiRequest', () => { it('throws a friendly error when the network request fails', async () => { vi.spyOn(global, 'fetch').mockRejectedValue(new Error('ECONNREFUSED')); - await expect(apiRequest({ method: 'GET', path: '/orgs' })).rejects.toThrow( - /Failed to connect to WorkOS API/, - ); + await expect(apiRequest({ method: 'GET', path: '/orgs' })).rejects.toThrow(/Failed to connect to WorkOS API/); }); }); From ff3b3e71d51b759364c10feca88b0d1110d2a535 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 21:40:02 +0000 Subject: [PATCH 09/17] fix(api): emit structured error from runApiInteractive in JSON mode When stdout/stdin is non-interactive but --json is requested, instead of printing a human-readable usage block to stdout (which corrupts machine-readable consumers) we now exit with a tty_required structured error on stderr. Co-Authored-By: nick.nisi@workos.com --- src/commands/api/index.spec.ts | 27 +++++++++++++++++++++++++++ src/commands/api/index.ts | 10 ++++++++++ 2 files changed, 37 insertions(+) diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index ebd34c4..db5ad99 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -86,13 +86,22 @@ function buildResponse(overrides: Partial = {}): ApiResponse { describe('runApiInteractive', () => { let consoleOutput: string[]; + let stderrOutput: string[]; + let exitSpy: ReturnType; beforeEach(() => { vi.clearAllMocks(); consoleOutput = []; + stderrOutput = []; vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { consoleOutput.push(args.map(String).join(' ')); }); + vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => { + stderrOutput.push(args.map(String).join(' ')); + }); + exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => { + throw new Error(`__exit__:${code ?? 0}`); + }) as never); }); afterEach(() => { @@ -101,10 +110,28 @@ describe('runApiInteractive', () => { }); it('prints usage instructions when stdin/stdout is non-interactive', async () => { + setOutputMode('human'); vi.mocked(isNonInteractiveEnvironment).mockReturnValueOnce(true); await runApiInteractive(); expect(consoleOutput.join('\n')).toContain('Interactive mode requires a TTY'); }); + + it('emits a structured tty_required error in JSON mode when non-interactive', async () => { + setOutputMode('json'); + vi.mocked(isNonInteractiveEnvironment).mockReturnValueOnce(true); + await expect(runApiInteractive()).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + expect(consoleOutput).toEqual([]); + const errorLine = stderrOutput.find((line) => { + try { + const parsed = JSON.parse(line) as { error?: { code?: string } }; + return parsed.error?.code === 'tty_required'; + } catch { + return false; + } + }); + expect(errorLine).toBeDefined(); + }); }); describe('runApiLs', () => { diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 0f02b6e..e7bb1cf 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -23,6 +23,16 @@ const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']); export async function runApiInteractive(): Promise { if (isNonInteractiveEnvironment()) { + if (isJsonMode()) { + exitWithError({ + code: 'tty_required', + message: 'Interactive mode requires a TTY. Provide an endpoint or use `workos api ls`.', + details: { + usage: ['workos api ', 'workos api ls [filter]'], + }, + }); + } + console.log( 'Interactive mode requires a TTY.\n\n' + 'Usage:\n' + From 2d87eb77ed9c258a01cb0d7d7a9d2bbc918af9ab Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 21:46:43 +0000 Subject: [PATCH 10/17] fix(api): respect empty bodies and require --yes for mutating JSON requests - resolveBody/runApiRequest now treat an explicit empty string body the same as any other body. Previously --data '' (or piping an empty file) would silently fall through to GET method inference and drop the body from dry-run/preview/confirm paths. - In JSON mode a mutating request without --yes now exits with a confirmation_required structured error instead of falling through to a human prompt that would corrupt machine-readable output. Co-Authored-By: nick.nisi@workos.com --- src/commands/api/index.spec.ts | 23 +++++++++++++++++++++++ src/commands/api/index.ts | 31 ++++++++++++++++++++----------- 2 files changed, 43 insertions(+), 11 deletions(-) diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index db5ad99..433f527 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -338,4 +338,27 @@ describe('runApiRequest', () => { expect(errorLine).toBeDefined(); expect(mockApiRequest).not.toHaveBeenCalled(); }); + + it('treats an empty --data string as a body so method inference does not flip to GET', async () => { + mockApiRequest.mockResolvedValue(buildResponse()); + await runApiRequest('/organizations', { data: '', yes: true }); + expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ method: 'POST', body: '' })); + }); + + it('exits with confirmation_required in JSON mode when a mutating request lacks --yes', async () => { + setOutputMode('json'); + await expect(runApiRequest('/organizations', { method: 'POST', data: '{}' })).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + expect(mockApiRequest).not.toHaveBeenCalled(); + expect(mockConfirm).not.toHaveBeenCalled(); + const errorLine = stderrOutput.find((line) => { + try { + const parsed = JSON.parse(line) as { error?: { code?: string } }; + return parsed.error?.code === 'confirmation_required'; + } catch { + return false; + } + }); + expect(errorLine).toBeDefined(); + }); }); diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index e7bb1cf..10400a9 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -95,13 +95,14 @@ export function runApiLs(filter?: string): void { export async function runApiRequest(endpoint: string, options: ApiCommandOptions): Promise { const body = await resolveBody(options); - const method = (options.method ?? (body ? 'POST' : 'GET')).toUpperCase(); + const hasBody = body !== undefined; + const method = (options.method ?? (hasBody ? 'POST' : 'GET')).toUpperCase(); const baseUrl = resolveApiBaseUrl(); if (options.dryRun) { if (isJsonMode()) { let parsedBody: unknown; - if (body) { + if (hasBody) { try { parsedBody = JSON.parse(body); } catch { @@ -116,18 +117,26 @@ export async function runApiRequest(endpoint: string, options: ApiCommandOptions }); } else { console.log(`${chalk.dim('[dry-run]')} ${method} ${baseUrl}${normalizePath(endpoint)}`); - if (body) prettyPrint(body); + if (hasBody) prettyPrint(body); } return; } - if (MUTATING_METHODS.has(method) && !options.yes && !isNonInteractiveEnvironment()) { - const clack = (await import('../../utils/clack.js')).default; - console.log(`\n${chalk.yellow('About to')} ${method} ${endpoint}`); - if (body) prettyPrint(body); - const ok = await clack.confirm({ message: 'Proceed?' }); - if (!ok || clack.isCancel(ok)) { - process.exit(0); + if (MUTATING_METHODS.has(method) && !options.yes) { + if (isJsonMode()) { + exitWithError({ + code: 'confirmation_required', + message: 'Mutating requests in JSON mode require --yes to keep stdout machine-readable.', + }); + } + if (!isNonInteractiveEnvironment()) { + const clack = (await import('../../utils/clack.js')).default; + console.log(`\n${chalk.yellow('About to')} ${method} ${endpoint}`); + if (hasBody) prettyPrint(body); + const ok = await clack.confirm({ message: 'Proceed?' }); + if (!ok || clack.isCancel(ok)) { + process.exit(0); + } } } @@ -152,7 +161,7 @@ function normalizePath(path: string): string { } async function resolveBody(options: ApiCommandOptions): Promise { - if (options.data) return options.data; + if (options.data !== undefined) return options.data; if (options.file) { if (options.file === '-') { const chunks: Buffer[] = []; From 0b23d7923ebbecd09982d5f9fd16312ee89b0daf Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 21:55:45 +0000 Subject: [PATCH 11/17] fix(api): close remaining bugs flagged by Devin Review and CodeRabbit - runApiRequest: refuse mutating requests without --yes in non-interactive human mode. Previously the control flow had a gap where a non-TTY environment with WORKOS_FORCE_TTY=1 (or any non-JSON, non-interactive setup) silently proceeded with the request. We now print a stderr error and exit 1 in that case so destructive operations are never executed implicitly. - bin.ts: register the shared insecure-storage option on the api command so applyInsecureStorage actually receives the flag instead of failing yargs strict-mode. - request.ts: send Content-Type: application/json whenever a body is defined (including the empty string), matching the new empty-body semantics in resolveBody. - interactive.spec.ts: add the missing test file alongside interactive.ts (per CLAUDE.md), covering tag/endpoint selection, path/query parameter substitution, JSON body collection, cancel paths, and >=400 response handling. Co-Authored-By: nick.nisi@workos.com --- src/bin.ts | 1 + src/commands/api/index.spec.ts | 10 ++ src/commands/api/index.ts | 18 +-- src/commands/api/interactive.spec.ts | 192 +++++++++++++++++++++++++++ src/commands/api/request.spec.ts | 9 ++ src/commands/api/request.ts | 4 +- 6 files changed, 224 insertions(+), 10 deletions(-) create mode 100644 src/commands/api/interactive.spec.ts diff --git a/src/bin.ts b/src/bin.ts index e0b92eb..bb71dd8 100644 --- a/src/bin.ts +++ b/src/bin.ts @@ -435,6 +435,7 @@ yargs(rawArgs) 'Make authenticated requests to the WorkOS API', (yargs) => yargs + .options(insecureStorageOption) .positional('endpoint', { type: 'string', describe: "API endpoint path (e.g. /users), or 'ls' to list endpoints", diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index 433f527..2927763 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -345,6 +345,16 @@ describe('runApiRequest', () => { expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ method: 'POST', body: '' })); }); + it('refuses mutating requests without --yes in non-interactive human mode', async () => { + setOutputMode('human'); + vi.mocked(isNonInteractiveEnvironment).mockReturnValueOnce(true); + await expect(runApiRequest('/organizations', { method: 'POST', data: '{}' })).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + expect(mockApiRequest).not.toHaveBeenCalled(); + expect(mockConfirm).not.toHaveBeenCalled(); + expect(stderrOutput.some((l) => l.includes('Refusing to POST'))).toBe(true); + }); + it('exits with confirmation_required in JSON mode when a mutating request lacks --yes', async () => { setOutputMode('json'); await expect(runApiRequest('/organizations', { method: 'POST', data: '{}' })).rejects.toThrow(/__exit__:1/); diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 10400a9..e24438d 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -129,14 +129,16 @@ export async function runApiRequest(endpoint: string, options: ApiCommandOptions message: 'Mutating requests in JSON mode require --yes to keep stdout machine-readable.', }); } - if (!isNonInteractiveEnvironment()) { - const clack = (await import('../../utils/clack.js')).default; - console.log(`\n${chalk.yellow('About to')} ${method} ${endpoint}`); - if (hasBody) prettyPrint(body); - const ok = await clack.confirm({ message: 'Proceed?' }); - if (!ok || clack.isCancel(ok)) { - process.exit(0); - } + if (isNonInteractiveEnvironment()) { + console.error(`Refusing to ${method} ${endpoint} without --yes in a non-interactive environment.`); + process.exit(1); + } + const clack = (await import('../../utils/clack.js')).default; + console.log(`\n${chalk.yellow('About to')} ${method} ${endpoint}`); + if (hasBody) prettyPrint(body); + const ok = await clack.confirm({ message: 'Proceed?' }); + if (!ok || clack.isCancel(ok)) { + process.exit(0); } } diff --git a/src/commands/api/interactive.spec.ts b/src/commands/api/interactive.spec.ts new file mode 100644 index 0000000..7b7ca6f --- /dev/null +++ b/src/commands/api/interactive.spec.ts @@ -0,0 +1,192 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import type { Catalog } from './catalog.js'; +import type { ApiResponse } from './request.js'; + +const mockCatalog: Catalog = { + endpoints: [ + { + method: 'GET', + path: '/users', + summary: 'List users', + tag: 'Users', + operationId: 'listUsers', + pathParams: [], + queryParams: [], + hasRequestBody: false, + }, + { + method: 'GET', + path: '/users/{id}', + summary: 'Get user', + tag: 'Users', + operationId: 'getUser', + pathParams: [{ name: 'id', description: 'User ID', required: true }], + queryParams: [{ name: 'expand', description: 'Expand fields', required: false }], + hasRequestBody: false, + }, + { + method: 'POST', + path: '/organizations', + summary: 'Create organization', + tag: 'Organizations', + operationId: 'createOrganization', + pathParams: [], + queryParams: [], + hasRequestBody: true, + }, + ], + tags: ['Organizations', 'Users'], +}; + +const mockApiRequest = vi.fn<(...args: unknown[]) => Promise>(); + +vi.mock('./catalog.js', async () => { + const actual = await vi.importActual('./catalog.js'); + return { + ...actual, + loadCatalog: () => mockCatalog, + }; +}); + +vi.mock('./request.js', () => ({ + apiRequest: (...args: unknown[]) => mockApiRequest(...args), +})); + +vi.mock('../../lib/api-key.js', () => ({ + resolveApiKey: vi.fn(() => 'sk_test'), + resolveApiBaseUrl: vi.fn(() => 'https://api.example.com'), +})); + +const mockSelect = vi.fn(); +const mockText = vi.fn(); +const mockConfirm = vi.fn(); +const cancelSymbol = Symbol('cancel'); +const mockIsCancel = vi.fn((value: unknown) => value === cancelSymbol); + +vi.mock('../../utils/clack.js', () => ({ + default: { + select: (...args: unknown[]) => mockSelect(...args), + text: (...args: unknown[]) => mockText(...args), + confirm: (...args: unknown[]) => mockConfirm(...args), + isCancel: (value: unknown) => mockIsCancel(value), + }, +})); + +const { apiInteractive } = await import('./interactive.js'); + +function buildResponse(overrides: Partial = {}): ApiResponse { + return { + status: 200, + headers: new Headers(), + body: { ok: true }, + rawBody: '{"ok":true}', + ...overrides, + }; +} + +describe('apiInteractive', () => { + let consoleOutput: string[]; + let exitSpy: ReturnType; + + beforeEach(() => { + vi.clearAllMocks(); + mockIsCancel.mockImplementation((value: unknown) => value === cancelSymbol); + consoleOutput = []; + vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => { + consoleOutput.push(args.map(String).join(' ')); + }); + exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => { + throw new Error(`__exit__:${code ?? 0}`); + }) as never); + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it('drives the happy path: select tag → endpoint → confirm → execute', async () => { + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[0]); + mockConfirm.mockResolvedValueOnce(true); + mockApiRequest.mockResolvedValueOnce(buildResponse()); + + await apiInteractive(); + + expect(mockApiRequest).toHaveBeenCalledWith( + expect.objectContaining({ + method: 'GET', + path: '/users', + apiKey: 'sk_test', + baseUrl: 'https://api.example.com', + }), + ); + }); + + it('substitutes path params and prompts for them', async () => { + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[1]); + mockText.mockResolvedValueOnce('user_42'); + // ep has a query param, decline adding it + mockConfirm.mockResolvedValueOnce(false).mockResolvedValueOnce(true); + mockApiRequest.mockResolvedValueOnce(buildResponse()); + + await apiInteractive(); + + expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ path: '/users/user_42' })); + }); + + it('appends URL-encoded query params when the user opts in', async () => { + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[1]); + mockText + .mockResolvedValueOnce('user 42') // path param + .mockResolvedValueOnce('first name'); // query param value + mockConfirm + .mockResolvedValueOnce(true) // wantsQuery + .mockResolvedValueOnce(true); // execute + mockApiRequest.mockResolvedValueOnce(buildResponse()); + + await apiInteractive(); + + // Path params are substituted verbatim; only query values are URL-encoded. + expect(mockApiRequest).toHaveBeenCalledWith( + expect.objectContaining({ path: '/users/user 42?expand=first%20name' }), + ); + }); + + it('collects a JSON request body when the user provides one', async () => { + mockSelect.mockResolvedValueOnce('Organizations').mockResolvedValueOnce(mockCatalog.endpoints[2]); + mockConfirm.mockResolvedValueOnce(true).mockResolvedValueOnce(true); + mockText.mockResolvedValueOnce('{"name":"Acme"}'); + mockApiRequest.mockResolvedValueOnce(buildResponse({ status: 201 })); + + await apiInteractive(); + + expect(mockApiRequest).toHaveBeenCalledWith( + expect.objectContaining({ method: 'POST', path: '/organizations', body: '{"name":"Acme"}' }), + ); + }); + + it('exits with code 0 when the user cancels at the category prompt', async () => { + mockSelect.mockResolvedValueOnce(cancelSymbol); + + await expect(apiInteractive()).rejects.toThrow(/__exit__:0/); + expect(exitSpy).toHaveBeenCalledWith(0); + expect(mockApiRequest).not.toHaveBeenCalled(); + }); + + it('exits with code 0 when the user declines the final confirmation', async () => { + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[0]); + mockConfirm.mockResolvedValueOnce(false); + + await expect(apiInteractive()).rejects.toThrow(/__exit__:0/); + expect(exitSpy).toHaveBeenCalledWith(0); + expect(mockApiRequest).not.toHaveBeenCalled(); + }); + + it('exits with code 1 when the response status is >= 400', async () => { + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[0]); + mockConfirm.mockResolvedValueOnce(true); + mockApiRequest.mockResolvedValueOnce(buildResponse({ status: 500, body: { error: 'boom' } })); + + await expect(apiInteractive()).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + }); +}); diff --git a/src/commands/api/request.spec.ts b/src/commands/api/request.spec.ts index 0374335..2ae1090 100644 --- a/src/commands/api/request.spec.ts +++ b/src/commands/api/request.spec.ts @@ -80,6 +80,15 @@ describe('apiRequest', () => { expect(headers['Content-Type']).toBeUndefined(); }); + it('still sets Content-Type when an explicit empty-string body is provided', async () => { + const fetchSpy = vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{}')); + await apiRequest({ method: 'POST', path: '/orgs', body: '' }); + const init = fetchSpy.mock.calls[0]![1]!; + const headers = init.headers as Record; + expect(headers['Content-Type']).toBe('application/json'); + expect(init.body).toBe(''); + }); + it('parses a JSON response body', async () => { vi.spyOn(global, 'fetch').mockResolvedValue(buildResponse('{"id":"org_123"}', { status: 200 })); const response = await apiRequest({ method: 'GET', path: '/orgs/org_123' }); diff --git a/src/commands/api/request.ts b/src/commands/api/request.ts index 53799f4..2aa330c 100644 --- a/src/commands/api/request.ts +++ b/src/commands/api/request.ts @@ -29,7 +29,7 @@ export async function apiRequest(options: ApiRequestOptions): Promise Date: Tue, 5 May 2026 22:12:48 +0000 Subject: [PATCH 12/17] fix(api): refuse JSON-mode interactive flow even in a TTY MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit If a user runs `workos api --json` from a real TTY, the previous guard only fired when the environment was already non-interactive, so the code fell through to apiInteractive() — which writes human-readable preview lines (`console.log`) to stdout before printResponse(), corrupting the JSON output contract. Hoist the isJsonMode() check ahead of the TTY check so JSON mode always exits with a structured tty_required error, regardless of TTY status. Add a regression test for the JSON-in-TTY case and adjust the existing JSON-mode tests so they don't queue mockReturnValueOnce values that would never be consumed (which leaked into later tests in the file). Co-Authored-By: nick.nisi@workos.com --- src/commands/api/index.spec.ts | 21 ++++++++++++++++++++- src/commands/api/index.ts | 23 +++++++++++++---------- 2 files changed, 33 insertions(+), 11 deletions(-) diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index 2927763..d7455c7 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -118,8 +118,27 @@ describe('runApiInteractive', () => { it('emits a structured tty_required error in JSON mode when non-interactive', async () => { setOutputMode('json'); - vi.mocked(isNonInteractiveEnvironment).mockReturnValueOnce(true); + // JSON mode short-circuits before the TTY check, so the underlying environment doesn't matter. + await expect(runApiInteractive()).rejects.toThrow(/__exit__:1/); + expect(exitSpy).toHaveBeenCalledWith(1); + expect(consoleOutput).toEqual([]); + const errorLine = stderrOutput.find((line) => { + try { + const parsed = JSON.parse(line) as { error?: { code?: string } }; + return parsed.error?.code === 'tty_required'; + } catch { + return false; + } + }); + expect(errorLine).toBeDefined(); + }); + + it('refuses to enter interactive mode in JSON mode even when a TTY is present', async () => { + setOutputMode('json'); + // Default mock returns false (TTY present); JSON mode must short-circuit + // before isNonInteractiveEnvironment() is even called. await expect(runApiInteractive()).rejects.toThrow(/__exit__:1/); + expect(isNonInteractiveEnvironment).not.toHaveBeenCalled(); expect(exitSpy).toHaveBeenCalledWith(1); expect(consoleOutput).toEqual([]); const errorLine = stderrOutput.find((line) => { diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index e24438d..310e4c5 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -22,17 +22,20 @@ export interface ApiCommandOptions { const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']); export async function runApiInteractive(): Promise { - if (isNonInteractiveEnvironment()) { - if (isJsonMode()) { - exitWithError({ - code: 'tty_required', - message: 'Interactive mode requires a TTY. Provide an endpoint or use `workos api ls`.', - details: { - usage: ['workos api ', 'workos api ls [filter]'], - }, - }); - } + // Interactive mode is inherently human-oriented (clack prompts, preview text, + // etc.). Refuse to enter it whenever JSON output was requested, regardless of + // TTY status, so stdout stays machine-readable. + if (isJsonMode()) { + exitWithError({ + code: 'tty_required', + message: 'Interactive mode is not available with --json. Provide an endpoint or use `workos api ls`.', + details: { + usage: ['workos api ', 'workos api ls [filter]'], + }, + }); + } + if (isNonInteractiveEnvironment()) { console.log( 'Interactive mode requires a TTY.\n\n' + 'Usage:\n' + From 37ef3b86691212a4a6d807cc8632c38f5ef30c3a Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 22:21:17 +0000 Subject: [PATCH 13/17] fix(api): expose --insecure-storage in help-json for the api command The api command's yargs builder registers insecureStorageOption (so the runtime accepts --insecure-storage), but the help-json schema omitted it, breaking the machine-readable contract documented for agents consuming `workos api --help --json`. Mirror the convention used by every other credential-accessing command in help-json.ts. Co-Authored-By: nick.nisi@workos.com --- src/utils/help-json.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/utils/help-json.ts b/src/utils/help-json.ts index 1a8f38b..f35a6c9 100644 --- a/src/utils/help-json.ts +++ b/src/utils/help-json.ts @@ -306,6 +306,7 @@ const commands: CommandSchema[] = [ { name: 'filter', type: 'string', description: 'Filter keyword (used with ls)', required: false }, ], options: [ + insecureStorageOpt, { name: 'method', type: 'string', From 4912d24d2cd606ec32a7d7c5efa73353180ea1c0 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 23:17:43 +0000 Subject: [PATCH 14/17] fix(api): tighten edge-case handling in body, path, and fetch flows Three small but real fixes prompted by code-review questions: * resolveBody: when --file - is used and stdin is empty, the previous code returned an empty string, which runApiRequest then treated as a valid body (silently flipping the inferred method to POST and firing an empty-body request). Now exits with a structured empty_stdin_body error so the user knows their pipe didn't deliver any data. * interactive.ts: path placeholder substitution used String.replace, which only replaces the first occurrence. The current WorkOS spec doesn't reuse a parameter name within a single path, but the OpenAPI format permits it; switch to replaceAll so a hypothetical path like /users/{id}/links/{id} is fully resolved. * request.ts: the fetch error handler discarded the original error entirely, leaving users staring at a generic 'check your internet connection' message even when the real cause was a DNS failure, TLS cert mismatch, or timeout. Preserve the underlying message in the thrown error and attach it as { cause } so it's surfaced when printed and accessible programmatically. Co-Authored-By: nick.nisi@workos.com --- src/commands/api/index.spec.ts | 24 ++++++++++++++++++++++++ src/commands/api/index.ts | 10 +++++++++- src/commands/api/interactive.spec.ts | 22 ++++++++++++++++++++++ src/commands/api/interactive.ts | 2 +- src/commands/api/request.spec.ts | 14 ++++++++++++++ src/commands/api/request.ts | 5 +++-- 6 files changed, 73 insertions(+), 4 deletions(-) diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index d7455c7..d881f38 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -390,4 +390,28 @@ describe('runApiRequest', () => { }); expect(errorLine).toBeDefined(); }); + + it('exits with empty_stdin_body when --file - is used and stdin is empty', async () => { + setOutputMode('json'); + // Replace process.stdin with an async iterator that yields no chunks (EOF immediately). + const emptyStdin = (async function* () {})(); + const originalStdin = process.stdin; + Object.defineProperty(process, 'stdin', { value: emptyStdin, configurable: true }); + try { + await expect(runApiRequest('/orgs', { file: '-', yes: true })).rejects.toThrow(/__exit__:1/); + } finally { + Object.defineProperty(process, 'stdin', { value: originalStdin, configurable: true }); + } + expect(exitSpy).toHaveBeenCalledWith(1); + expect(mockApiRequest).not.toHaveBeenCalled(); + const errorLine = stderrOutput.find((line) => { + try { + const parsed = JSON.parse(line) as { error?: { code?: string } }; + return parsed.error?.code === 'empty_stdin_body'; + } catch { + return false; + } + }); + expect(errorLine).toBeDefined(); + }); }); diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 310e4c5..297180f 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -173,7 +173,15 @@ async function resolveBody(options: ApiCommandOptions): Promise { expect(mockApiRequest).not.toHaveBeenCalled(); }); + it('replaces every occurrence of a repeated path placeholder', async () => { + const repeated = mockCatalog.endpoints[3]; + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(repeated); + mockText.mockResolvedValueOnce('user_42'); + mockConfirm.mockResolvedValueOnce(true); + mockApiRequest.mockResolvedValueOnce(buildResponse()); + + await apiInteractive(); + + expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ path: '/users/user_42/links/user_42' })); + }); + it('exits with code 1 when the response status is >= 400', async () => { mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[0]); mockConfirm.mockResolvedValueOnce(true); diff --git a/src/commands/api/interactive.ts b/src/commands/api/interactive.ts index b4ee150..46840da 100644 --- a/src/commands/api/interactive.ts +++ b/src/commands/api/interactive.ts @@ -46,7 +46,7 @@ export async function apiInteractive(): Promise { }, }), ); - resolvedPath = resolvedPath.replace(`{${param.name}}`, value.trim()); + resolvedPath = resolvedPath.replaceAll(`{${param.name}}`, value.trim()); } let queryString = ''; diff --git a/src/commands/api/request.spec.ts b/src/commands/api/request.spec.ts index 2ae1090..1e089ec 100644 --- a/src/commands/api/request.spec.ts +++ b/src/commands/api/request.spec.ts @@ -115,4 +115,18 @@ describe('apiRequest', () => { vi.spyOn(global, 'fetch').mockRejectedValue(new Error('ECONNREFUSED')); await expect(apiRequest({ method: 'GET', path: '/orgs' })).rejects.toThrow(/Failed to connect to WorkOS API/); }); + + it('preserves the original network error detail and cause for debugging', async () => { + const original = new Error('getaddrinfo ENOTFOUND api.workos.com'); + vi.spyOn(global, 'fetch').mockRejectedValue(original); + let caught: unknown; + try { + await apiRequest({ method: 'GET', path: '/orgs' }); + } catch (err) { + caught = err; + } + expect(caught).toBeInstanceOf(Error); + expect((caught as Error).message).toContain('getaddrinfo ENOTFOUND api.workos.com'); + expect((caught as Error).cause).toBe(original); + }); }); diff --git a/src/commands/api/request.ts b/src/commands/api/request.ts index 2aa330c..0636d92 100644 --- a/src/commands/api/request.ts +++ b/src/commands/api/request.ts @@ -40,8 +40,9 @@ export async function apiRequest(options: ApiRequestOptions): Promise Date: Tue, 5 May 2026 23:24:02 +0000 Subject: [PATCH 15/17] fix(api): URL-encode path param values in interactive mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile flagged a real P1: query param values were correctly wrapped in encodeURIComponent, but path param values were substituted verbatim. A user typing a value containing a space, '?', '#', '%', or '/' would end up with an invalid URL like 'https://api.workos.com/users/user 42', which Node's native fetch rejects with TypeError: Invalid URL — and our catch handler in request.ts then surfaces as 'Failed to connect to WorkOS API: Invalid URL', misleading the user into thinking it was a network issue. Apply encodeURIComponent to path param values before substitution and add a regression test for reserved characters. Co-Authored-By: nick.nisi@workos.com --- src/commands/api/interactive.spec.ts | 18 ++++++++++++++++-- src/commands/api/interactive.ts | 2 +- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/src/commands/api/interactive.spec.ts b/src/commands/api/interactive.spec.ts index b0149de..1db8ce5 100644 --- a/src/commands/api/interactive.spec.ts +++ b/src/commands/api/interactive.spec.ts @@ -155,12 +155,26 @@ describe('apiInteractive', () => { await apiInteractive(); - // Path params are substituted verbatim; only query values are URL-encoded. + // Both path and query values are URL-encoded so fetch() doesn't throw "Invalid URL" + // on values containing spaces or other URL-unsafe characters. expect(mockApiRequest).toHaveBeenCalledWith( - expect.objectContaining({ path: '/users/user 42?expand=first%20name' }), + expect.objectContaining({ path: '/users/user%2042?expand=first%20name' }), ); }); + it('URL-encodes path param values containing reserved characters', async () => { + mockSelect.mockResolvedValueOnce('Users').mockResolvedValueOnce(mockCatalog.endpoints[1]); + // Value with characters that would break URL parsing if substituted verbatim. + mockText.mockResolvedValueOnce('a/b?c#d'); + // No query params, then execute. + mockConfirm.mockResolvedValueOnce(false).mockResolvedValueOnce(true); + mockApiRequest.mockResolvedValueOnce(buildResponse()); + + await apiInteractive(); + + expect(mockApiRequest).toHaveBeenCalledWith(expect.objectContaining({ path: '/users/a%2Fb%3Fc%23d' })); + }); + it('collects a JSON request body when the user provides one', async () => { mockSelect.mockResolvedValueOnce('Organizations').mockResolvedValueOnce(mockCatalog.endpoints[2]); mockConfirm.mockResolvedValueOnce(true).mockResolvedValueOnce(true); diff --git a/src/commands/api/interactive.ts b/src/commands/api/interactive.ts index 46840da..f5d1978 100644 --- a/src/commands/api/interactive.ts +++ b/src/commands/api/interactive.ts @@ -46,7 +46,7 @@ export async function apiInteractive(): Promise { }, }), ); - resolvedPath = resolvedPath.replaceAll(`{${param.name}}`, value.trim()); + resolvedPath = resolvedPath.replaceAll(`{${param.name}}`, encodeURIComponent(value.trim())); } let queryString = ''; From a57f38dea6a1410d6bdb7499bc23848767bede2c Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 23:29:05 +0000 Subject: [PATCH 16/17] fix(api): resolve $ref params and dedupe path/operation overlap Greptile flagged two long-standing concerns in the OpenAPI catalog parser: 1. $ref parameters are silently dropped. The WorkOS spec doesn't use them today, but if it ever adopts shared parameter definitions under components.parameters, the prompt for that parameter would be skipped and the literal {param} placeholder would be sent to the API. Resolve refs against components.parameters (with chain following) and skip unresolvable refs explicitly. 2. Path-level + operation-level params with the same (name, in) pair were concatenated, producing duplicate prompts in interactive mode. Per the OpenAPI 3.x spec, operation-level params override path-level ones for the same (name, in). Switch to a Map keyed on "in:name" so the operation-level definition wins. Tests added in catalog.spec.ts cover $ref resolution, unresolvable refs (no placeholder leak), and path/operation override semantics. Co-Authored-By: nick.nisi@workos.com --- src/commands/api/catalog.spec.ts | 85 ++++++++++++++++++++++++++++++++ src/commands/api/catalog.ts | 54 +++++++++++++++++--- 2 files changed, 133 insertions(+), 6 deletions(-) diff --git a/src/commands/api/catalog.spec.ts b/src/commands/api/catalog.spec.ts index a0b11d8..40498bd 100644 --- a/src/commands/api/catalog.spec.ts +++ b/src/commands/api/catalog.spec.ts @@ -97,6 +97,91 @@ describe('parseSpec', () => { expect(catalog.tags).toEqual([]); }); + it('resolves $ref parameters against components.parameters', () => { + const yaml = ` +openapi: 3.0.0 +info: + title: Test + version: 1.0.0 +components: + parameters: + SharedId: + name: id + in: path + required: true + description: Shared id parameter + SharedLimit: + name: limit + in: query + required: false + description: Page size +paths: + /widgets/{id}: + parameters: + - $ref: '#/components/parameters/SharedId' + get: + operationId: getWidget + summary: Get widget + parameters: + - $ref: '#/components/parameters/SharedLimit' +`; + const catalog = parseSpec(yaml); + const ep = catalog.endpoints.find((e) => e.path === '/widgets/{id}' && e.method === 'GET'); + expect(ep?.pathParams).toEqual([{ name: 'id', description: 'Shared id parameter', required: true }]); + expect(ep?.queryParams).toEqual([{ name: 'limit', description: 'Page size', required: false }]); + }); + + it('skips $ref parameters that cannot be resolved instead of leaking placeholders', () => { + const yaml = ` +openapi: 3.0.0 +info: + title: Test + version: 1.0.0 +paths: + /widgets/{id}: + parameters: + - $ref: '#/components/parameters/Missing' + - name: id + in: path + required: true + description: Inline id + get: + operationId: getWidget + summary: Get widget +`; + const catalog = parseSpec(yaml); + const ep = catalog.endpoints[0]; + // The unresolvable $ref should be silently dropped; the inline param survives. + expect(ep?.pathParams).toEqual([{ name: 'id', description: 'Inline id', required: true }]); + }); + + it('deduplicates params by (name, in) — operation-level overrides path-level', () => { + const yaml = ` +openapi: 3.0.0 +info: + title: Test + version: 1.0.0 +paths: + /widgets/{id}: + parameters: + - name: id + in: path + required: true + description: From path-level + get: + operationId: getWidget + summary: Get widget + parameters: + - name: id + in: path + required: true + description: From operation-level (wins) +`; + const catalog = parseSpec(yaml); + const ep = catalog.endpoints[0]; + expect(ep?.pathParams).toEqual([{ name: 'id', description: 'From operation-level (wins)', required: true }]); + }); + it('falls back to "other" tag when none is provided', () => { const yaml = ` openapi: 3.0.0 diff --git a/src/commands/api/catalog.ts b/src/commands/api/catalog.ts index f712114..0f6491d 100644 --- a/src/commands/api/catalog.ts +++ b/src/commands/api/catalog.ts @@ -26,9 +26,40 @@ export interface Catalog { const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const; +interface RawParam { + name?: string; + in?: string; + description?: string; + required?: boolean; + $ref?: string; +} + +/** + * Resolve an OpenAPI 3.x parameter object that may itself be a $ref pointing + * into components.parameters. Returns undefined if the ref can't be resolved + * (so the parameter is skipped instead of producing a {param} placeholder + * that leaks into request URLs). + */ +function resolveParam(param: RawParam, componentParams: Record): RawParam | undefined { + if (!param || typeof param !== 'object') return undefined; + if (typeof param.$ref === 'string') { + const match = /^#\/components\/parameters\/(.+)$/.exec(param.$ref); + if (!match) return undefined; + const target = componentParams[match[1]!]; + if (!target) return undefined; + // Recurse so a chain of $refs still resolves to a concrete definition. + return resolveParam(target, componentParams); + } + return param; +} + export function parseSpec(yamlText: string): Catalog { - const spec = parseYaml(yamlText); + const spec = parseYaml(yamlText) as { + paths?: Record; + components?: { parameters?: Record }; + }; const endpoints: EndpointInfo[] = []; + const componentParams = spec.components?.parameters ?? {}; for (const [path, pathItem] of Object.entries(spec.paths ?? {})) { const pathObj = pathItem as Record; @@ -40,15 +71,26 @@ export function parseSpec(yamlText: string): Catalog { const op = operation as Record; const tag = ((op.tags as string[]) ?? ['other'])[0] ?? 'other'; - const allParams = [...((pathObj.parameters as unknown[]) ?? []), ...((op.parameters as unknown[]) ?? [])]; + // Resolve $ref and merge path-level + operation-level params. + // Operation-level params override path-level ones with the same (name, in) + // pair, per the OpenAPI 3.x spec. + const rawPathLevel = (pathObj.parameters as RawParam[] | undefined) ?? []; + const rawOpLevel = (op.parameters as RawParam[] | undefined) ?? []; + const merged = new Map(); + for (const raw of [...rawPathLevel, ...rawOpLevel]) { + const resolved = resolveParam(raw, componentParams); + if (!resolved || !resolved.name || !resolved.in) continue; + merged.set(`${resolved.in}:${resolved.name}`, resolved); + } + const allParams = [...merged.values()]; const pathParams: Param[] = allParams - .filter((p: any) => p.in === 'path') - .map((p: any) => ({ name: p.name, description: p.description ?? '', required: p.required ?? true })); + .filter((p) => p.in === 'path') + .map((p) => ({ name: p.name!, description: p.description ?? '', required: p.required ?? true })); const queryParams: Param[] = allParams - .filter((p: any) => p.in === 'query') - .map((p: any) => ({ name: p.name, description: p.description ?? '', required: p.required ?? false })); + .filter((p) => p.in === 'query') + .map((p) => ({ name: p.name!, description: p.description ?? '', required: p.required ?? false })); endpoints.push({ method: method.toUpperCase(), From 11e5ffb9aa93b9d838a056d027e2a3e52a8e544e Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 5 May 2026 23:40:34 +0000 Subject: [PATCH 17/17] fix(api): switch catalog spec read to async to match CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Devin Review flagged that loadCatalog() used readFileSync, violating CLAUDE.md's 'Avoid Node-specific sync APIs (crypto, fs sync) unless necessary' rule. Switch to fs/promises readFile and make loadCatalog return Promise. The cache now stores the in-flight Promise rather than the resolved value, so concurrent callers reuse the same readFile/parse pass — this also closes the (theoretical) race that Greptile and others kept flagging earlier in this PR. Cascading async-ification: * runApiLs becomes async and is awaited from bin.ts. * apiInteractive already awaited loadCatalog (was returning a sync Catalog before — now it gets a Promise, which it correctly awaits). Spec file mocks switched from () => mockCatalog to async () => mockCatalog so they match the new return type, and the four runApiLs tests now use await. Co-Authored-By: nick.nisi@workos.com --- src/bin.ts | 2 +- src/commands/api/catalog.ts | 19 ++++++++++++------- src/commands/api/index.spec.ts | 18 +++++++++--------- src/commands/api/index.ts | 4 ++-- src/commands/api/interactive.spec.ts | 2 +- src/commands/api/interactive.ts | 2 +- 6 files changed, 26 insertions(+), 21 deletions(-) diff --git a/src/bin.ts b/src/bin.ts index bb71dd8..4fe540e 100644 --- a/src/bin.ts +++ b/src/bin.ts @@ -497,7 +497,7 @@ yargs(rawArgs) } if (endpoint === 'ls') { - runApiLs(filter); + await runApiLs(filter); return; } diff --git a/src/commands/api/catalog.ts b/src/commands/api/catalog.ts index 0f6491d..6e58b53 100644 --- a/src/commands/api/catalog.ts +++ b/src/commands/api/catalog.ts @@ -1,6 +1,6 @@ import { parse as parseYaml } from 'yaml'; import { createRequire } from 'node:module'; -import { readFileSync } from 'node:fs'; +import { readFile } from 'node:fs/promises'; export interface Param { name: string; @@ -109,15 +109,20 @@ export function parseSpec(yamlText: string): Catalog { return { endpoints, tags }; } -let cachedCatalog: Catalog | undefined; +let cachedCatalog: Promise | undefined; -export function loadCatalog(): Catalog { +export function loadCatalog(): Promise { + // Cache the in-flight Promise (not just the resolved value) so concurrent + // callers reuse the same readFile/parse pass — see request.ts callers. if (cachedCatalog) return cachedCatalog; - const require = createRequire(import.meta.url); - const specPath = require.resolve('@workos/openapi-spec/spec'); - const yamlText = readFileSync(specPath, 'utf-8'); - cachedCatalog = parseSpec(yamlText); + cachedCatalog = (async () => { + const require = createRequire(import.meta.url); + const specPath = require.resolve('@workos/openapi-spec/spec'); + const yamlText = await readFile(specPath, 'utf-8'); + return parseSpec(yamlText); + })(); + return cachedCatalog; } diff --git a/src/commands/api/index.spec.ts b/src/commands/api/index.spec.ts index d881f38..daf5870 100644 --- a/src/commands/api/index.spec.ts +++ b/src/commands/api/index.spec.ts @@ -44,7 +44,7 @@ vi.mock('./catalog.js', async () => { const actual = await vi.importActual('./catalog.js'); return { ...actual, - loadCatalog: () => mockCatalog, + loadCatalog: async () => mockCatalog, }; }); @@ -169,9 +169,9 @@ describe('runApiLs', () => { setOutputMode('human'); }); - it('lists endpoints grouped by tag in human mode', () => { + it('lists endpoints grouped by tag in human mode', async () => { setOutputMode('human'); - runApiLs(); + await runApiLs(); const joined = consoleOutput.join('\n'); expect(joined).toContain('Users'); expect(joined).toContain('/users'); @@ -179,23 +179,23 @@ describe('runApiLs', () => { expect(joined).toContain('/organizations'); }); - it('filters endpoints by substring (path/tag/summary/operationId)', () => { + it('filters endpoints by substring (path/tag/summary/operationId)', async () => { setOutputMode('human'); - runApiLs('organization'); + await runApiLs('organization'); const joined = consoleOutput.join('\n'); expect(joined).toContain('/organizations'); expect(joined).not.toContain('/users'); }); - it('prints a friendly message when no endpoint matches the filter', () => { + it('prints a friendly message when no endpoint matches the filter', async () => { setOutputMode('human'); - runApiLs('does-not-exist'); + await runApiLs('does-not-exist'); expect(consoleOutput.some((l) => l.includes('No endpoints matching "does-not-exist"'))).toBe(true); }); - it('emits structured JSON in JSON mode', () => { + it('emits structured JSON in JSON mode', async () => { setOutputMode('json'); - runApiLs('users'); + await runApiLs('users'); expect(consoleOutput).toHaveLength(1); const parsed = JSON.parse(consoleOutput[0]!); expect(parsed.data).toEqual([ diff --git a/src/commands/api/index.ts b/src/commands/api/index.ts index 297180f..09f397e 100644 --- a/src/commands/api/index.ts +++ b/src/commands/api/index.ts @@ -52,8 +52,8 @@ export async function runApiInteractive(): Promise { await apiInteractive(); } -export function runApiLs(filter?: string): void { - const catalog = loadCatalog(); +export async function runApiLs(filter?: string): Promise { + const catalog = await loadCatalog(); let endpoints = catalog.endpoints; if (filter) { diff --git a/src/commands/api/interactive.spec.ts b/src/commands/api/interactive.spec.ts index 1db8ce5..b84f362 100644 --- a/src/commands/api/interactive.spec.ts +++ b/src/commands/api/interactive.spec.ts @@ -54,7 +54,7 @@ vi.mock('./catalog.js', async () => { const actual = await vi.importActual('./catalog.js'); return { ...actual, - loadCatalog: () => mockCatalog, + loadCatalog: async () => mockCatalog, }; }); diff --git a/src/commands/api/interactive.ts b/src/commands/api/interactive.ts index f5d1978..c0ef410 100644 --- a/src/commands/api/interactive.ts +++ b/src/commands/api/interactive.ts @@ -10,7 +10,7 @@ function assertNotCancelled(value: T | symbol): T { } export async function apiInteractive(): Promise { - const catalog = loadCatalog(); + const catalog = await loadCatalog(); const grouped = endpointsByTag(catalog.endpoints); const tag = assertNotCancelled(