diff --git a/.last-synced-sha b/.last-synced-sha index 6482b5e..67dd556 100644 --- a/.last-synced-sha +++ b/.last-synced-sha @@ -1 +1 @@ -4949f089632deb545a54c26f997fe022a56fdf20 +d9f8c88e1f76510c81a7ad325077b98121d18a4d diff --git a/spec/open-api-spec.yaml b/spec/open-api-spec.yaml index b411f1e..d7604c9 100644 --- a/spec/open-api-spec.yaml +++ b/spec/open-api-spec.yaml @@ -1,13 +1,12 @@ openapi: 3.1.1 paths: - /agents/claims/attempts: - patch: + /agents/blueprints: + post: description: >- - Link an external user to a claim attempt and retrieve the code needed - for the agent to complete the claim. The user is looked up by external - ID; if no user exists, one is created. When the user belongs to multiple - organizations, an explicit organization must be provided. - operationId: AgentAdminController_linkClaimAttemptToExternalUser + Creates an agent blueprint: the template describing what an agent may do + (its permission ceiling), who may invoke it, and the lifetimes of its + sessions. + operationId: AgentBlueprintsController_create parameters: [] requestBody: required: true @@ -16,62 +15,150 @@ paths: schema: type: object properties: - type: + name: type: string - description: >- - The operation to perform on the claim attempt. Currently - only `link_external_user` is supported. - example: link_external_user - const: link_external_user - claim_attempt_token: + minLength: 1 + maxLength: 255 + description: Human-readable name of the agent blueprint. + example: Prospecting Agent + description: type: string minLength: 1 - description: The token identifying the claim attempt. - example: cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY - user: + maxLength: 1000 + description: Human-readable description of the agent blueprint. + example: Finds and qualifies sales prospects. + permissions: + default: [] + type: array + items: + type: string + minLength: 1 + maxItems: 1000 + description: >- + Permission slugs forming the ceiling on what sessions minted + from this blueprint may do. Each slug must exist in the + environment. + example: + - crm:read + - email:send + invocable_by: + default: {} type: object properties: - email: - type: string - format: email - description: The email address of the user. - example: alice@example.com - external_id: - type: string - minLength: 1 - description: The external ID of the user. - example: user_abc123 + role_slugs: + default: [] + type: array + items: + type: string + minLength: 1 + maxItems: 100 + description: >- + Role slugs whose members may mint user-delegated + sessions from this blueprint. An empty list allows any + member. + example: + - manager + organization_ids: + default: [] + type: array + items: + type: string + minLength: 1 + maxItems: 1000 + description: >- + Organizations in which sessions may be minted from this + blueprint, enforced on user-delegated, autonomous, and + agent-delegated mints. An empty list allows any + organization in the environment. + example: + - org_01EHWNCE74X7JSDV0X3SZ3KJNY + description: Who may mint sessions from this blueprint. + session_settings: + type: object + properties: + max_age_seconds: + type: integer + exclusiveMinimum: 0 + maximum: 31536000 + description: >- + Maximum lifetime of a session in seconds; refreshes + never extend a session past this. At most 31,536,000 + (365 days). + example: 3600 + access_token_ttl_seconds: + type: integer + exclusiveMinimum: 0 + maximum: 3600 + description: >- + Lifetime of each minted access token in seconds. At most + 3,600 (1 hour). + example: 300 + refresh_token_ttl_seconds: + type: integer + exclusiveMinimum: 0 + maximum: 5184000 + description: >- + Lifetime of each rotated refresh token in seconds. At + most 5,184,000 (60 days). + example: 3600 required: - - email - - external_id - description: >- - The user to attach to the claim attempt, identified by email - and external ID. - example: - email: alice@example.com - external_id: user_abc123 - organization_id: - type: string - minLength: 1 + - max_age_seconds + - access_token_ttl_seconds + - refresh_token_ttl_seconds description: >- - The organization to place the agent in. Required when the - user belongs to more than one organization. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + Token and session lifetimes for sessions minted from this + blueprint. required: - - type - - claim_attempt_token - - user + - name + - session_settings + description: Configuration for the new agent blueprint. responses: - '200': - description: Claim attempt linked to external user. + '201': + description: Created content: application/json: schema: - $ref: '#/components/schemas/ClaimViewResponse' + $ref: '#/components/schemas/AgentBlueprint' '400': - description: >- - Invalid request, email mismatch, invalid claim, invalid - organization, or wrong account. + 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 + const: invalid_request + 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: + code: + type: string + description: The error code identifying the type of error. + example: name_already_in_use + const: name_already_in_use + 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: @@ -81,36 +168,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: invalid_request - const: invalid_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: invalid_claim - const: invalid_claim - 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_organization - const: invalid_organization + example: permission_not_found + const: permission_not_found message: type: string description: A human-readable description of the error. @@ -123,8 +182,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: email_mismatch - const: email_mismatch + example: role_not_found + const: role_not_found message: type: string description: A human-readable description of the error. @@ -137,8 +196,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: wrong_account - const: wrong_account + example: organization_not_found + const: organization_not_found message: type: string description: A human-readable description of the error. @@ -146,44 +205,334 @@ paths: required: - code - message - '403': - description: Claim denied or auth method disabled. + summary: Create an agent blueprint + tags: + - agents.blueprints + x-feature-flag: agent-blueprints-public-api + get: + description: Lists the agent blueprints in the current environment. + operationId: AgentBlueprintsController_list + parameters: + - name: before + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `before="obj_123"` to fetch a new batch + of objects before `"obj_123"`. + schema: + example: xxx_01HXYZ123456789ABCDEFGHIJ + type: string + - name: after + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `after="obj_123"` to fetch a new batch + of objects after `"obj_123"`. + schema: + example: xxx_01HXYZ987654321KJIHGFEDCBA + type: string + - name: limit + required: false + in: query + description: >- + Upper limit on the number of objects to return, between `1` and + `100`. + schema: + minimum: 1 + maximum: 100 + default: 10 + example: 10 + type: integer + - name: order + required: false + in: query + description: >- + Order the results by the creation time. Supported values are `"asc"` + (ascending), `"desc"` (descending), and `"normal"` (descending with + reversed cursor semantics where `before` fetches older records and + `after` fetches newer records). Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + responses: + '200': + description: OK content: application/json: schema: - oneOf: + allOf: - type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: claim_denied - const: claim_denied - message: + object: type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message + 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: agent_blueprint_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: agent_blueprint_01HXYZ987654321KJIHGFEDCBA + required: + - before + - after + description: >- + Pagination cursors for navigating between pages of + results. - type: object properties: - code: + data: + type: array + description: The list of records for the current page. + items: + $ref: '#/components/schemas/AgentBlueprint' + '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 + summary: List agent blueprints + tags: + - agents.blueprints + x-feature-flag: agent-blueprints-public-api + /agents/blueprints/{agent_blueprint_id}: + get: + description: Retrieves an agent blueprint by ID. + operationId: AgentBlueprintsController_get + parameters: + - name: agent_blueprint_id + required: true + in: path + description: The unique ID of the agent blueprint. + schema: + type: string + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentBlueprint' + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Get an agent blueprint + tags: + - agents.blueprints + x-feature-flag: agent-blueprints-public-api + patch: + description: >- + Updates an agent blueprint. Omitted fields are left unchanged; provided + lists replace the existing configuration. + operationId: AgentBlueprintsController_update + parameters: + - name: agent_blueprint_id + required: true + in: path + description: The unique ID of the agent blueprint. + schema: + type: string + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + description: Human-readable name of the agent blueprint. + example: Prospecting Agent + description: + type: + - string + - 'null' + minLength: 1 + maxLength: 1000 + description: >- + Human-readable description of the agent blueprint. Pass + `null` to clear it. + example: Finds and qualifies sales prospects. + permissions: + type: array + items: + type: string + minLength: 1 + maxItems: 1000 + description: >- + Permission slugs forming the ceiling on what sessions minted + from this blueprint may do. Each slug must exist in the + environment. + example: + - crm:read + - email:send + invocable_by: + type: object + properties: + role_slugs: + type: array + items: type: string - description: The error code identifying the type of error. - example: auth_method_disabled - const: auth_method_disabled - message: + minLength: 1 + maxItems: 100 + description: >- + Role slugs whose members may mint user-delegated + sessions from this blueprint. An empty list allows any + member. + example: + - manager + organization_ids: + type: array + items: type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message + minLength: 1 + maxItems: 1000 + description: >- + Organizations in which sessions may be minted from this + blueprint, enforced on user-delegated, autonomous, and + agent-delegated mints. An empty list allows any + organization in the environment. + example: + - org_01EHWNCE74X7JSDV0X3SZ3KJNY + description: >- + Who may mint sessions from this blueprint. Omitted lists are + left unchanged. + session_settings: + type: object + properties: + max_age_seconds: + type: integer + exclusiveMinimum: 0 + maximum: 31536000 + description: >- + Maximum lifetime of a session in seconds; refreshes + never extend a session past this. At most 31,536,000 + (365 days). + example: 3600 + access_token_ttl_seconds: + type: integer + exclusiveMinimum: 0 + maximum: 3600 + description: >- + Lifetime of each minted access token in seconds. At most + 3,600 (1 hour). + example: 300 + refresh_token_ttl_seconds: + type: integer + exclusiveMinimum: 0 + maximum: 5184000 + description: >- + Lifetime of each rotated refresh token in seconds. At + most 5,184,000 (60 days). + example: 3600 + description: >- + Token and session lifetimes for sessions minted from this + blueprint. Omitted fields are left unchanged. + description: >- + Fields to update on the agent blueprint. Omitted fields are left + unchanged; provided lists replace the existing configuration. + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentBlueprint' + '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 + const: invalid_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: >- - Organization selection required, email already in use, or claim - already completed. + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: name_already_in_use + const: name_already_in_use + 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: @@ -193,42 +542,22 @@ paths: code: type: string description: The error code identifying the type of error. - example: organization_selection_required - const: organization_selection_required + example: permission_not_found + const: permission_not_found message: type: string description: A human-readable description of the error. example: Request could not be processed. - organizations: - type: array - items: - type: object - properties: - id: - type: string - description: The organization ID. - example: org_01EHWNCE74X7JSDV0X3SZ3KJNY - name: - type: string - description: The organization name. - example: Acme Corp - required: - - id - - name - description: >- - Organizations the user belongs to. Pick one and retry - with organization_id. required: - code - message - - organizations - type: object properties: code: type: string description: The error code identifying the type of error. - example: email_already_in_use - const: email_already_in_use + example: role_not_found + const: role_not_found message: type: string description: A human-readable description of the error. @@ -241,8 +570,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: already_claimed - const: already_claimed + example: organization_not_found + const: organization_not_found message: type: string description: A human-readable description of the error. @@ -250,52 +579,61 @@ paths: required: - code - message - '410': - description: Claim or user code has expired. + summary: Update an agent blueprint + tags: + - agents.blueprints + x-feature-flag: agent-blueprints-public-api + delete: + description: >- + Deletes an agent blueprint along with its configuration, instances, and + sessions. + operationId: AgentBlueprintsController_delete + parameters: + - name: agent_blueprint_id + required: true + in: path + description: The unique ID of the agent blueprint. + schema: + type: string + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '204': + description: Agent blueprint deleted. + '404': + description: Not Found content: application/json: schema: - oneOf: - - type: object - properties: - code: - type: string - description: The error code identifying the type of error. - example: claim_expired - const: claim_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: user_code_expired - const: user_code_expired - message: - type: string - description: A human-readable description of the error. - example: Request could not be processed. - required: - - code - - message - summary: Link a claim attempt to an external user + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Delete an agent blueprint tags: - - agents - x-feature-flag: agent-auth-public-api - /agents/credentials/validate: + - agents.blueprints + x-feature-flag: agent-blueprints-public-api + /agents/blueprints/{agent_blueprint_id}/tokens: post: description: >- - Validate an agent credential — an API key or access token — against the - environment of the API key used to authenticate the request. This is a - read-only check: it never consumes or mutates the credential. - operationId: AgentAdminController_validateCredential - parameters: [] + Mint an agent access token (and backing session) from an agent + blueprint. The session can be user-delegated (exchanging a user access + token), autonomous (the agent acting as itself in an organization), + agent-delegated (the agent exchanging its own access token for a new + session on the same instance), or a refresh of a previously issued + refresh token. + operationId: AgentBlueprintsTokenController_mintToken + parameters: + - name: agent_blueprint_id + required: true + in: path + description: The unique ID of the agent blueprint. + schema: + type: string + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY requestBody: required: true content: @@ -309,102 +647,2718 @@ paths: type: type: string description: >- - The kind of credential being validated — an agent API - key or an agent access token. - const: api_key - credential: + How the session is minted: `user_delegated`, + `autonomous`, `agent_delegated`, or `refresh`. + const: user_delegated + user_access_token: type: string minLength: 1 description: >- - The credential value to validate: the API key value for - `api_key`, or the access token (JWT) for `access_token`. - example: sk_agent_example_1234567890 + The access token of the user delegating to the agent. + The token identifies the user and organization; + effective permissions are resolved server-side. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6... + intent: + type: string + minLength: 1 + maxLength: 255 + description: >- + Optional caller-supplied context, echoed as an object + with a `text` field in the `intent` claim of the minted + access token. + example: renew-contract-123 required: - type - - credential + - user_access_token - type: object properties: type: type: string description: >- - The kind of credential being validated — an agent API - key or an agent access token. - const: access_token - credential: + How the session is minted: `user_delegated`, + `autonomous`, `agent_delegated`, or `refresh`. + const: autonomous + organization_id: type: string minLength: 1 description: >- - The credential value to validate: the API key value for - `api_key`, or the access token (JWT) for `access_token`. + The organization the agent acts within when operating as + itself. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + intent: + type: string + minLength: 1 + maxLength: 255 + description: >- + Optional caller-supplied context, echoed as an object + with a `text` field in the `intent` claim of the minted + access token. + example: renew-contract-123 + required: + - type + - organization_id + - type: object + properties: + type: + type: string + description: >- + How the session is minted: `user_delegated`, + `autonomous`, `agent_delegated`, or `refresh`. + const: agent_delegated + agent_access_token: + type: string + minLength: 1 + description: >- + The agent's own access token to exchange for a new + session on the same instance. The token must have been + minted from this blueprint; permissions are re-derived + from current authority. example: eyJhbGciOiJSUzI1NiIsImtpZCI6... - audience: + intent: type: string minLength: 1 + maxLength: 255 description: >- - When provided, the access token's `aud` claim is - verified against this value. Tokens issued for a - different resource are rejected. - example: https://api.example.com + Optional caller-supplied context, echoed as an object + with a `text` field in the `intent` claim of the minted + access token. + example: renew-contract-123 required: - type - - credential + - agent_access_token + - type: object + properties: + type: + type: string + description: >- + How the session is minted: `user_delegated`, + `autonomous`, `agent_delegated`, or `refresh`. + const: refresh + refresh_token: + type: string + minLength: 1 + description: >- + The refresh token issued with a previous agent access + token. Refresh tokens are single-use: each refresh + rotates it. + example: njGkA8Wyht0GBEGGA0Zh1Q3wZzL2... + intent: + type: string + minLength: 1 + maxLength: 255 + description: >- + Optional caller-supplied context, echoed as an object + with a `text` field in the `intent` claim of the minted + access token. + example: renew-contract-123 + required: + - type + - refresh_token description: >- - The agent credential to validate. Either an `api_key` or an - `access_token`, discriminated by `type`. + How to mint the agent session, discriminated by `type`. `intent` + is optional on every variant. responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AgentCredentialValidation' + $ref: '#/components/schemas/AgentToken' '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 + const: invalid_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: invalid_user_access_token + const: invalid_user_access_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: invalid_agent_access_token + const: invalid_agent_access_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: invalid_refresh_token + const: invalid_refresh_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: session_revoked + const: session_revoked + 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: session_expired + const: session_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: user_session_ended + const: user_session_ended + 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: max_age_exceeded + const: max_age_exceeded + 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: session_settings_not_found + const: session_settings_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: chain_depth_exceeded + const: chain_depth_exceeded + 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: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: user_not_member_of_organization + const: user_not_member_of_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: organization_not_invocable + const: organization_not_invocable + 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_not_invocable + const: role_not_invocable + 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: - code: - type: string - description: The error code identifying the type of error. - example: invalid_request - const: invalid_request message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - summary: Validate an agent credential + summary: Mint an agent token + tags: + - agents.blueprints.tokens + x-feature-flag: agent-blueprints-public-api + /agents/claims/attempts: + patch: + description: >- + Link an external user to a claim attempt and retrieve the code needed + for the agent to complete the claim. The user is looked up by external + ID; if no user exists, one is created. When the user belongs to multiple + organizations, an explicit organization must be provided. + operationId: AgentAdminController_linkClaimAttemptToExternalUser + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + type: + type: string + description: >- + The operation to perform on the claim attempt. Currently + only `link_external_user` is supported. + example: link_external_user + const: link_external_user + claim_attempt_token: + type: string + minLength: 1 + description: The token identifying the claim attempt. + example: cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY + user: + type: object + properties: + email: + type: string + format: email + description: The email address of the user. + example: alice@example.com + external_id: + type: string + minLength: 1 + description: The external ID of the user. + example: user_abc123 + required: + - email + - external_id + description: >- + The user to attach to the claim attempt, identified by email + and external ID. + example: + email: alice@example.com + external_id: user_abc123 + organization_id: + type: string + minLength: 1 + description: >- + The organization to place the agent in. Required when the + user belongs to more than one organization. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - type + - claim_attempt_token + - user + responses: + '200': + description: Claim attempt linked to external user. + content: + application/json: + schema: + $ref: '#/components/schemas/ClaimViewResponse' + '400': + description: >- + Invalid request, email mismatch, invalid claim, invalid + organization, or wrong account. + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: invalid_request + const: invalid_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: invalid_claim + const: invalid_claim + 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_organization + const: invalid_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: email_mismatch + const: email_mismatch + 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: wrong_account + const: wrong_account + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '403': + description: Claim denied or auth method disabled. + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: claim_denied + const: claim_denied + 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: auth_method_disabled + const: auth_method_disabled + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '409': + description: >- + Organization selection required, email already in use, or claim + already completed. + content: + application/json: + schema: + oneOf: + - 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. + organizations: + type: array + items: + type: object + properties: + id: + type: string + description: The organization ID. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: The organization name. + example: Acme Corp + required: + - id + - name + description: >- + Organizations the user belongs to. Pick one and retry + with organization_id. + required: + - code + - message + - organizations + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: email_already_in_use + const: email_already_in_use + 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: already_claimed + const: already_claimed + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + '410': + description: Claim or user code has expired. + content: + application/json: + schema: + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: claim_expired + const: claim_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: user_code_expired + const: user_code_expired + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + summary: Link a claim attempt to an external user tags: - - agents + - agents.registrations x-feature-flag: agent-auth-public-api - /agents/registrations/{id}: + /agents/credentials/validate: + post: + description: >- + Validate an agent credential — an API key or access token — against the + environment of the API key used to authenticate the request. This is a + read-only check: it never consumes or mutates the credential. + operationId: AgentAdminController_validateCredential + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + discriminator: + propertyName: type + oneOf: + - type: object + properties: + type: + type: string + description: >- + The kind of credential being validated — an agent API + key or an agent access token. + const: api_key + credential: + type: string + minLength: 1 + description: >- + The credential value to validate: the API key value for + `api_key`, or the access token (JWT) for `access_token`. + example: sk_agent_example_1234567890 + required: + - type + - credential + - type: object + properties: + type: + type: string + description: >- + The kind of credential being validated — an agent API + key or an agent access token. + const: access_token + credential: + type: string + minLength: 1 + description: >- + The credential value to validate: the API key value for + `api_key`, or the access token (JWT) for `access_token`. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6... + audience: + type: string + minLength: 1 + description: >- + When provided, the access token's `aud` claim is + verified against this value. Tokens issued for a + different resource are rejected. + example: https://api.example.com + required: + - type + - credential + description: >- + The agent credential to validate. Either an `api_key` or an + `access_token`, discriminated by `type`. + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentCredentialValidation' + '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 + const: invalid_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + summary: Validate an agent credential + tags: + - agents.registrations + x-feature-flag: agent-auth-public-api + /agents/instances: + get: + description: >- + Lists the agent instances in the current environment. Instances are + created implicitly when tokens are minted. + operationId: AgentInstancesController_list + parameters: + - name: before + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `before="obj_123"` to fetch a new batch + of objects before `"obj_123"`. + schema: + example: xxx_01HXYZ123456789ABCDEFGHIJ + type: string + - name: after + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `after="obj_123"` to fetch a new batch + of objects after `"obj_123"`. + schema: + example: xxx_01HXYZ987654321KJIHGFEDCBA + type: string + - name: limit + required: false + in: query + description: >- + Upper limit on the number of objects to return, between `1` and + `100`. + schema: + minimum: 1 + maximum: 100 + default: 10 + example: 10 + type: integer + - name: order + required: false + in: query + description: >- + Order the results by the creation time. Supported values are `"asc"` + (ascending), `"desc"` (descending), and `"normal"` (descending with + reversed cursor semantics where `before` fetches older records and + `after` fetches newer records). Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - name: organization_id + required: false + in: query + description: Only return instances acting within this organization. + schema: + type: string + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: agent_blueprint_id + required: false + in: query + description: Only return instances minted from this blueprint. + schema: + type: string + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + 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: agent_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: agent_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/AgentInstance' + '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 + summary: List agent instances + tags: + - agents.instances + x-feature-flag: agent-blueprints-public-api + /agents/instances/{agent_instance_id}: + get: + description: Retrieves an agent instance by ID. + operationId: AgentInstancesController_get + parameters: + - name: agent_instance_id + required: true + in: path + description: The unique ID of the agent instance. + schema: + type: string + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentInstance' + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Get an agent instance + tags: + - agents.instances + x-feature-flag: agent-blueprints-public-api + delete: + description: >- + Deletes an agent instance along with its sessions, invalidating their + refresh tokens. + operationId: AgentInstancesController_delete + parameters: + - name: agent_instance_id + required: true + in: path + description: The unique ID of the agent instance. + schema: + type: string + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '204': + description: Agent instance deleted. + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Delete an agent instance + tags: + - agents.instances + x-feature-flag: agent-blueprints-public-api + /agents/registrations/{id}: + get: + description: >- + Retrieve the details of an agent registration by ID. The registration is + scoped to the environment of the API key used to authenticate the + request. + operationId: AgentAdminController_getRegistration + parameters: + - name: id + required: true + in: path + description: The unique ID of the agent registration. + schema: + type: string + example: agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRegistration' + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Get an agent registration + tags: + - agents.registrations + x-feature-flag: agent-auth-public-api + /agents/sessions: + get: + description: >- + Lists the agent instance sessions in the current environment. Sessions + are created when tokens are minted. + operationId: AgentInstanceSessionsController_list + parameters: + - name: before + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `before="obj_123"` to fetch a new batch + of objects before `"obj_123"`. + schema: + example: xxx_01HXYZ123456789ABCDEFGHIJ + type: string + - name: after + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `after="obj_123"` to fetch a new batch + of objects after `"obj_123"`. + schema: + example: xxx_01HXYZ987654321KJIHGFEDCBA + type: string + - name: limit + required: false + in: query + description: >- + Upper limit on the number of objects to return, between `1` and + `100`. + schema: + minimum: 1 + maximum: 100 + default: 10 + example: 10 + type: integer + - name: order + required: false + in: query + description: >- + Order the results by the creation time. Supported values are `"asc"` + (ascending), `"desc"` (descending), and `"normal"` (descending with + reversed cursor semantics where `before` fetches older records and + `after` fetches newer records). Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - name: agent_blueprint_id + required: false + in: query + description: Only return sessions of instances minted from this blueprint. + schema: + type: string + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + - name: agent_instance_id + required: false + in: query + description: Only return sessions belonging to this agent instance. + schema: + type: string + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + 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: agent_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: agent_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: + $ref: '#/components/schemas/AgentInstanceSession' + '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 + '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 + summary: List agent instance sessions + tags: + - agents.sessions + x-feature-flag: agent-blueprints-public-api + /agents/sessions/{agent_instance_session_id}: + get: + description: Retrieves an agent instance session by ID. + operationId: AgentInstanceSessionsController_get + parameters: + - name: agent_instance_session_id + required: true + in: path + description: The unique ID of the agent instance session. + schema: + type: string + example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentInstanceSession' + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Get an agent instance session + tags: + - agents.sessions + x-feature-flag: agent-blueprints-public-api + /agents/sessions/{agent_instance_session_id}/revoke: + post: + description: >- + Revokes an agent instance session, invalidating its refresh token and + every access token minted under it. Revocation is idempotent: revoking + an already-revoked session keeps the original `revoked_at`, and revoking + an already-expired session returns the session with `status: expired` + and a null `revoked_at`. + operationId: AgentInstanceSessionsController_revoke + parameters: + - name: agent_instance_session_id + required: true + in: path + description: The unique ID of the agent instance session. + schema: + type: string + example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AgentInstanceSession' + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Revoke an agent instance session + tags: + - agents.sessions + x-feature-flag: agent-blueprints-public-api + /api_keys/validations: + post: + description: Validate an API key value and return the API key object if valid. + operationId: ApiKeysController_validateApiKey + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ValidateApiKeyDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKeyValidationResponse' + '401': + description: Unauthorized + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Validate API key + tags: + - api_keys + /api_keys/{id}: + delete: + description: >- + Permanently deletes an API key. This action cannot be undone. Once + deleted, any requests using this API key will fail authentication. + operationId: ApiKeysController_delete + parameters: + - name: id + required: true + in: path + description: The unique ID of the API key. + schema: + type: string + example: api_key_01EHZNVPK3SFK441A1RGBFSHRT + responses: + '204': + description: No Content + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Delete an API key + tags: + - api_keys + /api_keys/{id}/expire: + post: + description: >- + Expire an API key immediately, schedule a future expiration, or clear a + scheduled future expiration. + operationId: ApiKeysController_expire + parameters: + - name: id + required: true + in: path + description: The unique ID of the API key. + schema: + type: string + example: api_key_01EHZNVPK3SFK441A1RGBFSHRT + requestBody: + required: false + content: + application/json: + schema: + $ref: '#/components/schemas/ExpireApiKeyDto' + examples: + immediateExpiration: + summary: Expire immediately + value: {} + scheduleExpiration: + summary: Schedule an expiration + value: + expires_at: '2030-01-01T00:00:00.000Z' + clearExpiration: + summary: Clear a scheduled expiration + value: + expires_at: null + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKey' + example: + object: api_key + id: api_key_01EHZNVPK3SFK441A1RGBFSHRT + owner: + type: organization + id: org_01EHZNVPK3SFK441A1RGBFSHRT + name: Production API Key + obfuscated_value: sk_...3456 + last_used_at: null + expires_at: '2030-01-01T00:00:00.000Z' + permissions: + - posts:read + - posts:write + 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: 'API Key not found: ''api_key_01EHZNVPK3SFK441A1RGBFSHRT''.' + required: + - message + x-inline-with-overrides: true + '409': + description: Conflict + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: api_key_already_expired + const: api_key_already_expired + message: + type: string + description: A human-readable description of the error. + example: API key is already expired + required: + - code + - message + x-inline-with-overrides: true + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Expire an API key + tags: + - api_keys + /audit_logs/actions: + get: + description: Get a list of all Audit Log actions in the current environment. + operationId: AuditLogValidatorsController_list + parameters: + - name: before + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. + 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. Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + 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 + summary: List Actions + tags: + - audit-logs + /audit_logs/actions/{actionName}/schemas: + post: + 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. + operationId: AuditLogValidatorVersionsController_create + 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 + summary: Create Schema + tags: + - audit-logs + get: + description: >- + Get a list of all schemas for the Audit Logs action identified by + `:name`. + operationId: AuditLogValidatorVersionsController_schemas + 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. Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + 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 + summary: List Schemas + tags: + - audit-logs + /audit_logs/events: + post: + 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. + operationId: AuditLogEventsController_create + 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: '' + summary: Create Event + tags: + - audit-logs + /audit_logs/exports: + post: + description: >- + Create an Audit Log Export. Exports are scoped to a single organization + within a specified date range. + operationId: AuditLogExportsController_exports + 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 + summary: Create Export + tags: + - audit-logs + /audit_logs/exports/{auditLogExportId}: + get: + 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. + operationId: AuditLogExportsController_export + 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'. + summary: Get Export + tags: + - audit-logs + /auth/challenges/{id}/verify: + post: + description: Verifies an Authentication Challenge. + operationId: AuthenticationChallengesController_verify + 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 + summary: Verify Challenge + tags: + - multi-factor-auth.challenges + /auth/factors/enroll: + post: + 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. + operationId: AuthenticationFactorsController_create + 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 + summary: Enroll Factor + tags: + - multi-factor-auth + /auth/factors/{id}: + get: + description: Gets an Authentication Factor. + operationId: AuthenticationFactorsController_get + 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 + summary: Get Factor + tags: + - multi-factor-auth + delete: + description: Permanently deletes an Authentication Factor. It cannot be undone. + operationId: AuthenticationFactorsController_delete + 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 + summary: Delete Factor + tags: + - multi-factor-auth + /auth/factors/{id}/challenge: + post: + description: Creates a Challenge for an Authentication Factor. + operationId: AuthenticationFactorsController_challenge + 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 + summary: Challenge Factor + tags: + - multi-factor-auth + /authkit/oauth2/complete: + post: + 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. + operationId: ExternalAuthController_completeLogin + 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: user_consent_options_not_supported + const: user_consent_options_not_supported + 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 + summary: Complete external authentication + tags: + - workos-connect + /authorization/groups/{group_id}/role_assignments: + get: + description: >- + List all role assignments granted to a group. Each assignment represents + a role granted to the group on a resource. + operationId: AuthorizationGroupRoleAssignmentsController_list + parameters: + - name: group_id + required: true + in: path + description: The ID 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GroupRoleAssignmentList' + '403': + description: Forbidden + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + '404': + description: Not Found + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: List role assignments for a group + tags: + - authorization + post: + description: Assign a role to a group on a specific resource. + operationId: AuthorizationGroupRoleAssignmentsController_create + parameters: + - name: group_id + 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/CreateGroupRoleAssignmentDto' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/GroupRoleAssignment' + '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: duplicate_group_role_assignment + const: duplicate_group_role_assignment + 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 + summary: Assign a role to a group + tags: + - authorization + put: + description: >- + Replace all role assignments for a group with the provided list. + Existing assignments not in the list will be removed. + operationId: AuthorizationGroupRoleAssignmentsController_replaceGroupRoleAssignments + parameters: + - name: group_id + 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/ReplaceGroupRoleAssignmentsDto' + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GroupRoleAssignmentList' + '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 + summary: Replace all role assignments for a group + tags: + - authorization + delete: + description: >- + Remove role assignments from a group that match the provided criteria. + Returns 404 when no matching active assignment is found. + operationId: AuthorizationGroupRoleAssignmentsController_removeGroupRoleAssignments + parameters: + - name: group_id + 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/DeleteGroupRoleAssignmentsByCriteriaDto' + 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 + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Remove group role assignments by criteria + tags: + - authorization + /authorization/groups/{group_id}/role_assignments/{role_assignment_id}: get: - description: >- - Retrieve the details of an agent registration by ID. The registration is - scoped to the environment of the API key used to authenticate the - request. - operationId: AgentAdminController_getRegistration + description: Get a specific role assignment for a group by its ID. + operationId: AuthorizationGroupRoleAssignmentsController_get parameters: - - name: id + - name: group_id required: true in: path - description: The unique ID of the agent registration. + description: The ID of the group. schema: type: string - example: agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY + example: group_01HXYZ123456789ABCDEFGHIJ + - name: role_assignment_id + required: true + in: path + description: The ID of the group role assignment. + schema: + type: string + example: gra_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AgentRegistration' - '404': - description: Not Found + $ref: '#/components/schemas/GroupRoleAssignment' + '403': + description: Forbidden content: application/json: schema: @@ -416,32 +3370,8 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get an agent registration - tags: - - agents - x-feature-flag: agent-auth-public-api - /api_keys/validations: - post: - description: Validate an API key value and return the API key object if valid. - operationId: ApiKeysController_validateApiKey - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/ValidateApiKeyDto' - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/ApiKeyValidationResponse' - '401': - description: Unauthorized - '422': - description: Unprocessable Entity + '404': + description: Not Found content: application/json: schema: @@ -453,26 +3383,43 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Validate API key + summary: Get a group role assignment tags: - - api_keys - /api_keys/{id}: + - authorization delete: - description: >- - Permanently deletes an API key. This action cannot be undone. Once - deleted, any requests using this API key will fail authentication. - operationId: ApiKeysController_delete + description: Remove a specific role assignment from a group by its ID. + operationId: AuthorizationGroupRoleAssignmentsController_removeGroupRoleAssignment parameters: - - name: id + - name: group_id required: true in: path - description: The unique ID of the API key. + description: The ID of the group. schema: type: string - example: api_key_01EHZNVPK3SFK441A1RGBFSHRT + example: group_01HXYZ123456789ABCDEFGHIJ + - name: role_assignment_id + required: true + in: path + description: The ID of the group role assignment to remove. + schema: + type: string + example: gra_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: @@ -486,65 +3433,39 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Delete an API key + summary: Remove a group role assignment tags: - - api_keys - /api_keys/{id}/expire: + - authorization + /authorization/organization_memberships/{organization_membership_id}/check: post: description: >- - Expire an API key immediately, schedule a future expiration, or clear a - scheduled future expiration. - operationId: ApiKeysController_expire + 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. + operationId: AuthorizationController_check parameters: - - name: id + - name: organization_membership_id required: true in: path - description: The unique ID of the API key. + description: The ID of the organization membership to check. schema: type: string - example: api_key_01EHZNVPK3SFK441A1RGBFSHRT + example: om_01HXYZ123456789ABCDEFGHIJ requestBody: - required: false + required: true content: application/json: schema: - $ref: '#/components/schemas/ExpireApiKeyDto' - examples: - immediateExpiration: - summary: Expire immediately - value: {} - scheduleExpiration: - summary: Schedule an expiration - value: - expires_at: '2030-01-01T00:00:00.000Z' - clearExpiration: - summary: Clear a scheduled expiration - value: - expires_at: null + $ref: '#/components/schemas/CheckAuthorizationDto' responses: '200': + description: OK content: application/json: schema: - $ref: '#/components/schemas/ApiKey' - example: - object: api_key - id: api_key_01EHZNVPK3SFK441A1RGBFSHRT - owner: - type: organization - id: org_01EHZNVPK3SFK441A1RGBFSHRT - name: Production API Key - obfuscated_value: sk_...3456 - last_used_at: null - expires_at: '2030-01-01T00:00:00.000Z' - permissions: - - posts:read - - posts:write - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - description: OK - '404': - description: Not Found + $ref: '#/components/schemas/AuthorizationCheck' + '403': + description: Forbidden content: application/json: schema: @@ -553,30 +3474,22 @@ paths: message: type: string description: A human-readable description of the error. - example: 'API Key not found: ''api_key_01EHZNVPK3SFK441A1RGBFSHRT''.' + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - x-inline-with-overrides: true - '409': - description: Conflict + '404': + description: Not Found content: application/json: schema: type: object properties: - code: - type: string - description: The error code identifying the type of error. - example: api_key_already_expired - const: api_key_already_expired message: type: string description: A human-readable description of the error. - example: API key is already expired + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - x-inline-with-overrides: true '422': description: Unprocessable Entity content: @@ -590,31 +3503,62 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Expire an API key + summary: Check authorization tags: - - api_keys - /audit_logs/actions: + - 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: - description: Get a list of all Audit Log actions in the current environment. - operationId: AuditLogValidatorsController_list + 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. + operationId: AuthorizationController_listResourcesForMembership 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. + 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: obj_1234567890 + 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. + 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: obj_1234567890 + example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false @@ -631,71 +3575,83 @@ paths: - name: order required: false in: query - description: Order the results by the creation time. Defaults to `normal`. + 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 `normal`. schema: $ref: '#/components/schemas/PaginationOrder' + - 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: - 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 + $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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '422': - description: Unprocessable Entity + '403': + description: Forbidden content: application/json: schema: @@ -707,37 +3663,19 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List Actions - tags: - - audit-logs - /audit_logs/actions/{actionName}/schemas: - post: - 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. - operationId: AuditLogValidatorVersionsController_create - 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 + '404': + description: Not Found content: application/json: schema: - $ref: '#/components/schemas/AuditLogSchemaJson' + 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: @@ -751,39 +3689,66 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Create Schema + summary: List resources for organization membership tags: - - audit-logs + - 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: description: >- - Get a list of all schemas for the Audit Logs action identified by - `:name`. - operationId: AuditLogValidatorVersionsController_schemas + Returns all permissions the organization membership effectively has on a + resource, including permissions inherited through roles assigned to + ancestor resources. Results are not filtered by the resource type: a + permission is returned whenever a check for it on this resource would be + authorized, and each permission is labeled with the resource type it is + declared on. + operationId: AuthorizationController_listEffectivePermissions parameters: - - name: actionName + - name: organization_membership_id required: true in: path - description: The name of the Audit Log action. + 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: - example: user.logged_in 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. + 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: obj_1234567890 + 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. + 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: obj_1234567890 + example: xxx_01HXYZ987654321KJIHGFEDCBA type: string - name: limit required: false @@ -800,7 +3765,11 @@ paths: - name: order required: false in: query - description: Order the results by the creation time. Defaults to `normal`. + 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 `normal`. schema: $ref: '#/components/schemas/PaginationOrder' responses: @@ -809,47 +3778,20 @@ paths: 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' + $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: @@ -876,109 +3818,96 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List Schemas + summary: List effective permissions for an organization membership on a resource tags: - - audit-logs - /audit_logs/events: - post: + - authorization + /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions: + get: 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. - operationId: AuditLogEventsController_create + 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. Results are not filtered + by the resource type: a permission is returned whenever a check for it + on this resource would be authorized, and each permission is labeled + with the resource type it is declared on. + operationId: AuthorizationController_listEffectivePermissionsByExternalId parameters: - - name: idempotency-key - in: header + - 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: >- - 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. + 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 - example: 884793cd-bef4-46cf-8790-e3d4957a09ce - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AuditLogEventIngestionDto' + - 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' 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': + $ref: '#/components/schemas/AuthorizationPermissionList' + '403': + description: Forbidden content: application/json: schema: @@ -990,46 +3919,21 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - example: - message: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + '404': 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. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - errors - message - example: - message: Validation failed. - errors: - - code: required - field: event.action + '422': description: Unprocessable Entity - '429': content: application/json: schema: @@ -1038,118 +3942,118 @@ paths: 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 + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - - code - example: - message: Too many requests. - code: rate_limit_exceeded - description: '' - summary: Create Event - tags: - - audit-logs - /audit_logs/exports: - post: - description: >- - Create an Audit Log Export. Exports are scoped to a single organization - within a specified date range. - operationId: AuditLogExportsController_exports - 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 - summary: Create Export + summary: >- + List effective permissions for an organization membership on a resource + by external ID tags: - - audit-logs - /audit_logs/exports/{auditLogExportId}: + - authorization + /authorization/organization_memberships/{organization_membership_id}/role_assignments: get: 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. - operationId: AuditLogExportsController_export + 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. + operationId: AuthorizationRoleAssignmentsController_listRoleAssignments parameters: - - name: auditLogExportId + - name: organization_membership_id required: true in: path - description: The unique ID of the Audit Log Export. + description: The ID of the organization membership. schema: type: string - example: audit_log_export_01GBZK5MP7TD1YCFQHFR22180V + 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - name: resource_id + required: false + in: query + description: Filter assignments by the ID of the resource. + schema: + example: authz_resource_01HXYZ123456789ABCDEFGH + type: string + - name: resource_external_id + required: false + in: query + description: Filter assignments by the external ID of the resource. + schema: + example: project-ext-456 + type: string + - name: resource_type_slug + required: false + in: query + description: Filter assignments by the slug of the resource type. + schema: + example: project + type: string responses: '200': - description: The Audit Log Export object. + description: OK 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' + $ref: '#/components/schemas/UserRoleAssignmentList' + '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: Audit Log Export not found. + description: Not Found content: application/json: schema: @@ -1161,63 +4065,60 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - example: - message: >- - Audit Log Export not found: - 'audit_log_export_01GBZK5MP7TD1YCFQHFR22180V'. - summary: Get Export + summary: List role assignments tags: - - audit-logs - /auth/challenges/{id}/verify: + - authorization post: - description: Verifies an Authentication Challenge. - operationId: AuthenticationChallengesController_verify + description: Assign a role to an organization membership on a specific resource. + operationId: AuthorizationRoleAssignmentsController_assignRole parameters: - - name: id + - name: organization_membership_id required: true in: path - description: The unique ID of the Authentication Challenge. + description: The ID of the organization membership. schema: type: string - example: auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ + example: om_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: - type: object - properties: - code: - type: string - description: The one-time code to verify. - example: '123456' - required: - - code + $ref: '#/components/schemas/AssignRoleDto' responses: '201': - description: Created content: application/json: schema: - $ref: '#/components/schemas/AuthenticationChallengeVerifyResponse' - '400': - description: Bad Request + $ref: '#/components/schemas/UserRoleAssignment' + example: + object: role_assignment + id: role_assignment_01HXYZ123456789ABCDEFGH + organization_membership_id: om_01HXYZ123456789ABCDEFGHIJ + role: + slug: editor + resource: + id: authz_resource_01HXYZ123456789ABCDEFGH + external_id: project-ext-456 + resource_type_slug: project + source: + type: direct + group_role_assignment_id: null + 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: - 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. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message '404': description: Not Found @@ -1245,59 +4146,40 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Verify Challenge + summary: Assign a role tags: - - multi-factor-auth.challenges - /auth/factors/enroll: - post: - 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. - operationId: AuthenticationFactorsController_create - parameters: [] + - 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: + description: Remove a role assignment by role slug and resource. + operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria + 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: - 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 + $ref: '#/components/schemas/RemoveRoleDto' responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/AuthenticationFactorEnrolled' - '422': - description: Unprocessable Entity + '204': + description: Role assignment removed successfully. + '403': + description: Forbidden content: application/json: schema: @@ -1309,38 +4191,6 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Enroll Factor - tags: - - multi-factor-auth - /auth/factors/{id}: - get: - description: Gets an Authentication Factor. - operationId: AuthenticationFactorsController_get - 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: @@ -1354,25 +4204,66 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get Factor + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Remove a role assignment tags: - - multi-factor-auth + - 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: - description: Permanently deletes an Authentication Factor. It cannot be undone. - operationId: AuthenticationFactorsController_delete + description: Remove a role assignment using its ID. + operationId: AuthorizationRoleAssignmentsController_removeRoleById parameters: - - name: id + - name: organization_membership_id required: true in: path - description: The unique ID of the Factor. + description: The ID of the organization membership. schema: type: string - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + 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: - '200': - description: OK '204': - description: No Content + 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: @@ -1386,49 +4277,122 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Delete Factor + summary: Remove a role assignment by ID tags: - - multi-factor-auth - /auth/factors/{id}/challenge: + - authorization + /authorization/organizations/{organizationId}/roles: post: - description: Creates a Challenge for an Authentication Factor. - operationId: AuthenticationFactorsController_challenge + description: Create a new custom role for this organization. + operationId: AuthorizationOrganizationRolesController_create parameters: - - name: id + - name: organizationId required: true in: path - description: The unique ID of the Authentication Factor to be challenged. + description: The ID of the organization. schema: type: string - example: auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ + example: org_01EHZNVPK3SFK441A1RGBFSHRT requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/ChallengeAuthenticationFactorDto' + $ref: '#/components/schemas/CreateOrganizationRoleDto' responses: '201': description: Created content: application/json: schema: - $ref: '#/components/schemas/AuthenticationChallenge' - '404': - description: Not Found + 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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '422': - description: Unprocessable Entity + '403': + description: Forbidden content: application/json: schema: @@ -1440,141 +4404,6 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Challenge Factor - tags: - - multi-factor-auth - /authkit/oauth2/complete: - post: - 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. - operationId: ExternalAuthController_completeLogin - 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: user_consent_options_not_supported - const: user_consent_options_not_supported - 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: @@ -1588,6 +4417,25 @@ paths: 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: @@ -1601,76 +4449,29 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Complete external authentication + summary: Create a custom role tags: - - workos-connect - /authorization/groups/{group_id}/role_assignments: + - authorization get: description: >- - List all role assignments granted to a group. Each assignment represents - a role granted to the group on a resource. - operationId: AuthorizationGroupRoleAssignmentsController_list + Get a list of all roles that apply to an organization. This includes + both environment roles and custom roles, returned in priority order. + operationId: AuthorizationOrganizationRolesController_list parameters: - - name: group_id + - name: organizationId required: true in: path - description: The ID 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"`. + description: The ID of the organization. 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' + example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/GroupRoleAssignmentList' + $ref: '#/components/schemas/RoleList' '403': description: Forbidden content: @@ -1697,80 +4498,119 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List role assignments for a group + summary: List custom roles tags: - authorization - post: - description: Assign a role to a group on a specific resource. - operationId: AuthorizationGroupRoleAssignmentsController_create + /authorization/organizations/{organizationId}/roles/{slug}: + get: + description: >- + Retrieve a role that applies to an organization by its slug. This can + return either an environment role or a custom role. + operationId: AuthorizationOrganizationRolesController_get parameters: - - name: group_id + - name: organizationId required: true in: path - description: The ID of the group. + description: The ID of the organization. schema: type: string - example: group_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateGroupRoleAssignmentDto' + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug + required: true + in: path + description: The slug of the role. + schema: + type: string + example: org-billing-admin responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/GroupRoleAssignment' - '403': - description: Forbidden + '200': + description: OK content: application/json: schema: type: object properties: - message: + slug: 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: + description: A unique slug for the role. + example: org-billing-admin + object: type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + 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: - - message - '409': - description: '' + - 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: - code: - type: string - description: The error code identifying the type of error. - example: duplicate_group_role_assignment - const: duplicate_group_role_assignment + type: object + properties: message: type: string description: A human-readable description of the error. - example: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - '422': - description: Unprocessable Entity + '404': + description: Not Found content: application/json: schema: @@ -1782,99 +4622,128 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Assign a role to a group + summary: Get a custom role tags: - authorization - put: + patch: description: >- - Replace all role assignments for a group with the provided list. - Existing assignments not in the list will be removed. - operationId: AuthorizationGroupRoleAssignmentsController_replaceGroupRoleAssignments + Update an existing custom role. Only the fields provided in the request + body will be updated. + operationId: AuthorizationOrganizationRolesController_update parameters: - - name: group_id + - name: organizationId required: true in: path - description: The ID of the group. + description: The ID of the organization. schema: type: string - example: group_01HXYZ123456789ABCDEFGHIJ + 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/ReplaceGroupRoleAssignmentsDto' + $ref: '#/components/schemas/UpdateOrganizationRoleDto' responses: '200': description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GroupRoleAssignmentList' - '403': - description: Forbidden content: application/json: schema: type: object properties: - message: + slug: 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: + description: A unique slug for the role. + example: org-billing-admin + object: type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + 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: - - message - '422': - description: Unprocessable Entity + - 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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - summary: Replace all role assignments for a group - tags: - - authorization - delete: - description: >- - Remove role assignments from a group that match the provided criteria. - Returns 404 when no matching active assignment is found. - operationId: AuthorizationGroupRoleAssignmentsController_removeGroupRoleAssignments - parameters: - - name: group_id - 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/DeleteGroupRoleAssignmentsByCriteriaDto' - responses: - '204': - description: No Content '403': description: Forbidden content: @@ -1914,85 +4783,49 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Remove group role assignments by criteria + summary: Update a custom role tags: - authorization - /authorization/groups/{group_id}/role_assignments/{role_assignment_id}: - get: - description: Get a specific role assignment for a group by its ID. - operationId: AuthorizationGroupRoleAssignmentsController_get + delete: + description: Delete an existing custom role. + operationId: AuthorizationOrganizationRolesController_delete parameters: - - name: group_id + - name: organizationId required: true in: path - description: The ID of the group. + description: The ID of the organization. schema: type: string - example: group_01HXYZ123456789ABCDEFGHIJ - - name: role_assignment_id + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug required: true in: path - description: The ID of the group role assignment. + description: The slug of the role. schema: type: string - example: gra_01HXYZ123456789ABCDEFGHIJ + example: org-admin responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/GroupRoleAssignment' - '403': - description: Forbidden + '204': + description: No Content + '400': + description: Bad Request content: application/json: schema: type: object properties: - message: + code: 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: + 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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - summary: Get a group role assignment - tags: - - authorization - delete: - description: Remove a specific role assignment from a group by its ID. - operationId: AuthorizationGroupRoleAssignmentsController_removeGroupRoleAssignment - parameters: - - name: group_id - required: true - in: path - description: The ID of the group. - schema: - type: string - example: group_01HXYZ123456789ABCDEFGHIJ - - name: role_assignment_id - required: true - in: path - description: The ID of the group role assignment to remove. - schema: - type: string - example: gra_01HXYZ123456789ABCDEFGHIJ - responses: - '204': - description: No Content '403': description: Forbidden content: @@ -2019,37 +4852,144 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Remove a group role assignment + '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 + summary: Delete a custom role tags: - authorization - /authorization/organization_memberships/{organization_membership_id}/check: - post: - 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. - operationId: AuthorizationController_check + /authorization/organizations/{organizationId}/roles/{slug}/permissions: + put: + description: Replace all permissions on a custom role with the provided list. + operationId: AuthorizationOrganizationRolePermissionsController_setPermissions parameters: - - name: organization_membership_id + - name: organizationId required: true in: path - description: The ID of the organization membership to check. + description: The ID of the organization. schema: type: string - example: om_01HXYZ123456789ABCDEFGHIJ + 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/CheckAuthorizationDto' + $ref: '#/components/schemas/SetRolePermissionsDto' responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationCheck' + 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: @@ -2089,134 +5029,108 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Check authorization + summary: Set permissions for a custom role 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: + post: 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. - operationId: AuthorizationController_listResourcesForMembership + Add a single permission to a custom role. If the permission is already + assigned to the role, this operation has no effect. + operationId: AuthorizationOrganizationRolePermissionsController_addPermission parameters: - - name: organization_membership_id + - name: organizationId 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"`. + description: The ID of the organization. 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - name: permission_slug + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: 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`. + in: path + description: The slug of the role. schema: type: string - example: external_project_123 + example: org-admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AddRolePermissionDto' responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationResourceList' + 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: @@ -2275,96 +5189,42 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List resources for organization membership + summary: Add a permission to a custom role 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: - description: >- - Returns all permissions the organization membership effectively has on a - resource, including permissions inherited through roles assigned to - ancestor resources. Results are not filtered by the resource type: a - permission is returned whenever a check for it on this resource would be - authorized, and each permission is labeled with the resource type it is - declared on. - operationId: AuthorizationController_listEffectivePermissions + /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}: + delete: + description: Remove a single permission from a custom role by its slug. + operationId: AuthorizationOrganizationRolePermissionsController_removePermission parameters: - - name: organization_membership_id + - name: organizationId required: true in: path - description: The ID of the organization membership. + description: The ID of the organization. schema: type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - name: resource_id + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: slug 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"`. + description: The slug of the role. 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"`. + example: org-admin + - name: permissionSlug + required: true + in: path + description: The slug of the permission to remove. 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' + example: documents:read responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationPermissionList' + $ref: '#/components/schemas/Role' '403': description: Forbidden content: @@ -2391,107 +5251,46 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: List effective permissions for an organization membership on a resource + summary: Remove a permission from a custom role tags: - authorization - /authorization/organization_memberships/{organization_membership_id}/resources/{resource_type_slug}/{external_id}/permissions: + /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}: get: 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. Results are not filtered - by the resource type: a permission is returned whenever a check for it - on this resource would be authorized, and each permission is labeled - with the resource type it is declared on. - operationId: AuthorizationController_listEffectivePermissionsByExternalId + 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. + operationId: AuthorizationResourcesByExternalIdController_getByExternalId parameters: - - name: organization_membership_id + - name: organization_id required: true in: path - description: The ID of the organization membership. + description: The ID of the organization that owns the resource. schema: type: string - example: om_01HXYZ123456789ABCDEFGHIJ + example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug required: true in: path description: The slug of the resource type. schema: type: string - example: document + 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: 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' + example: proj-456 responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationPermissionList' + $ref: '#/components/schemas/AuthorizationResource' '403': description: Forbidden content: @@ -2518,209 +5317,129 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: >- - List effective permissions for an organization membership on a resource - by external ID + summary: Get a resource by external ID tags: - authorization - /authorization/organization_memberships/{organization_membership_id}/role_assignments: - get: - 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. - operationId: AuthorizationRoleAssignmentsController_listRoleAssignments + patch: + description: Update an existing authorization resource using its external ID. + operationId: AuthorizationResourcesByExternalIdController_updateByExternalId parameters: - - name: organization_membership_id + - name: organization_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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - name: resource_id - required: false - in: query - description: Filter assignments by the ID of the resource. - schema: - example: authz_resource_01HXYZ123456789ABCDEFGH - type: string - - name: resource_external_id - required: false - in: query - description: Filter assignments by the external ID of the resource. + description: The ID of the organization that owns the resource. schema: - example: project-ext-456 type: string + example: org_01EHZNVPK3SFK441A1RGBFSHRT - name: resource_type_slug - required: false - in: query - description: Filter assignments by the slug of the resource type. + required: true + in: path + description: The slug of the resource type. schema: - example: project type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserRoleAssignmentList' - '403': - description: Forbidden - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - '404': - description: Not Found - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: List role assignments - tags: - - authorization - post: - description: Assign a role to an organization membership on a specific resource. - operationId: AuthorizationRoleAssignmentsController_assignRole - parameters: - - name: organization_membership_id + example: project + - name: external_id required: true in: path - description: The ID of the organization membership. + description: An identifier you provide to reference the resource in your system. schema: type: string - example: om_01HXYZ123456789ABCDEFGHIJ + example: proj-456 requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/AssignRoleDto' + $ref: '#/components/schemas/UpdateAuthorizationResourceDto' responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/UserRoleAssignment' - example: - object: role_assignment - id: role_assignment_01HXYZ123456789ABCDEFGH - organization_membership_id: om_01HXYZ123456789ABCDEFGHIJ - role: - slug: editor - resource: - id: authz_resource_01HXYZ123456789ABCDEFGH - external_id: project-ext-456 - resource_type_slug: project - source: - type: direct - group_role_assignment_id: null - created_at: '2026-01-15T12:00:00.000Z' - updated_at: '2026-01-15T12:00:00.000Z' - description: Created - '403': - description: Forbidden + '200': + description: OK content: application/json: schema: type: object properties: - message: + object: type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + 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: - - message - '404': - description: Not Found + - 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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '422': - description: Unprocessable Entity + '403': + description: Forbidden content: application/json: schema: @@ -2732,40 +5451,8 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Assign a role - 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: - description: Remove a role assignment by role slug and resource. - operationId: AuthorizationRoleAssignmentsController_removeRoleByCriteria - 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 + '404': + description: Not Found content: application/json: schema: @@ -2777,18 +5464,24 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '404': - description: Not Found + '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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message '422': description: Unprocessable Entity @@ -2803,40 +5496,78 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Remove a role assignment + summary: Update a resource by external ID tags: - authorization - x-mutually-exclusive-body-groups: &ref_5 - resource_target: - optional: false + x-mutually-exclusive-body-groups: &ref_0 + parent_resource: + optional: true variants: by_id: - - resource_id + - parent_resource_id by_external_id: - - resource_external_id - - resource_type_slug - /authorization/organization_memberships/{organization_membership_id}/role_assignments/{role_assignment_id}: + - parent_resource_external_id + - parent_resource_type_slug delete: - description: Remove a role assignment using its ID. - operationId: AuthorizationRoleAssignmentsController_removeRoleById + description: >- + Delete an authorization resource by organization, resource type, and + external ID. This also deletes all descendant resources. + operationId: AuthorizationResourcesByExternalIdController_deleteByExternalId parameters: - - name: organization_membership_id + - name: organization_id required: true in: path - description: The ID of the organization membership. + description: The ID of the organization that owns the resource. schema: type: string - example: om_01HXYZ123456789ABCDEFGHIJ - - name: role_assignment_id + example: org_01EHZNVPK3SFK441A1RGBFSHRT + - name: resource_type_slug required: true in: path - description: The ID of the role assignment to remove. + description: The slug of the resource type. schema: type: string - example: role_assignment_01HXYZ123456789ABCDEFGH + 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: Role assignment removed successfully. + 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: @@ -2863,101 +5594,149 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Remove a role assignment by ID + '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 + summary: Delete an authorization resource by external ID tags: - authorization - /authorization/organizations/{organizationId}/roles: - post: - description: Create a new custom role for this organization. - operationId: AuthorizationOrganizationRolesController_create + /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships: + get: + 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. + operationId: >- + AuthorizationResourcesByExternalIdController_listOrganizationMembershipsForResourceByExternalId parameters: - - name: organizationId + - name: organization_id required: true in: path - description: The ID of the organization. + description: The ID of the organization that owns the resource. schema: - type: string example: org_01EHZNVPK3SFK441A1RGBFSHRT - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateOrganizationRoleDto' + 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - 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: - '201': - description: Created + '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 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 + $ref: >- + #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList '400': description: Bad Request content: @@ -3003,25 +5782,6 @@ paths: 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: @@ -3035,29 +5795,99 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Create a custom role + summary: List memberships for a resource by external ID tags: - authorization + /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/role_assignments: get: description: >- - Get a list of all roles that apply to an organization. This includes - both environment roles and custom roles, returned in priority order. - operationId: AuthorizationOrganizationRolesController_list + List all role assignments granted on a resource, identified by its + external ID. Each assignment includes the organization membership it was + granted to. + operationId: >- + AuthorizationRoleAssignmentsController_listRoleAssignmentsForResourceByExternalId parameters: - - name: organizationId + - name: organization_id required: true in: path - description: The ID of the organization. + 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: 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - name: role_slug + required: false + in: query + description: Filter assignments by the slug of the role. + schema: + example: editor + type: string responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/RoleList' + $ref: '#/components/schemas/UserRoleAssignmentList' '403': description: Forbidden content: @@ -3084,117 +5914,67 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List custom roles + summary: List role assignments for a resource by external ID tags: - authorization - /authorization/organizations/{organizationId}/roles/{slug}: + /authorization/permissions: get: - description: >- - Retrieve a role that applies to an organization by its slug. This can - return either an environment role or a custom role. - operationId: AuthorizationOrganizationRolesController_get + description: Get a list of all permissions in your WorkOS environment. + operationId: AuthorizationPermissionsController_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. + - 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 - 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 + - 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + responses: + '200': + description: OK content: application/json: schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message + $ref: '#/components/schemas/AuthorizationPermissionList' '404': description: Not Found content: @@ -3208,87 +5988,66 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get a custom role + summary: List permissions tags: - - authorization - patch: + - permissions + post: description: >- - Update an existing custom role. Only the fields provided in the request - body will be updated. - operationId: AuthorizationOrganizationRolesController_update - 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 + Create a new permission in your WorkOS environment. The permission can + then be assigned to environment roles and custom roles. + operationId: AuthorizationPermissionsController_create + parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/UpdateOrganizationRoleDto' + $ref: '#/components/schemas/CreateAuthorizationPermissionDto' responses: - '200': - description: OK + '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 + description: Distinguishes the Permission object. + const: permission id: type: string - description: Unique identifier of the role. - example: role_01EHQMYV6MBK39QC5PZXHY59C3 + 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 role. - example: Finance Administrator + description: A descriptive name for the Permission. + example: View Documents description: type: - string - 'null' - description: An optional description of the role. - example: Can manage all financial operations - type: - type: string - enum: - - EnvironmentRole - - OrganizationRole + description: An optional description of the Permission. + example: Allows viewing document contents + system: + type: boolean description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole + 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 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 + description: >- + The slug of the resource type associated with the + permission. + example: document created_at: format: date-time type: string @@ -3300,14 +6059,13 @@ paths: description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - - slug - object - id + - slug - name - description - - type + - system - resource_type_slug - - permissions - created_at - updated_at x-inline-with-overrides: true @@ -3330,8 +6088,8 @@ paths: required: - code - message - '403': - description: Forbidden + '404': + description: Not Found content: application/json: schema: @@ -3343,18 +6101,24 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '404': - description: Not Found + '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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message '422': description: Unprocessable Entity @@ -3369,49 +6133,76 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Update a custom role + summary: Create a permission tags: - - authorization - delete: - description: Delete an existing custom role. - operationId: AuthorizationOrganizationRolesController_delete + - permissions + /authorization/permissions/{slug}: + get: + description: Retrieve a permission by its unique slug. + operationId: AuthorizationPermissionsController_find 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. + 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 - example: org-admin responses: - '204': - description: No Content - '400': - description: Bad Request + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationPermission' + '404': + description: Not Found 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. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message + summary: Get a permission + tags: + - permissions + patch: + description: >- + Update an existing permission. Only the fields provided in the request + body will be updated. + operationId: AuthorizationPermissionsController_update + 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: @@ -3438,146 +6229,54 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '409': - description: '' + '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: 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 - summary: Delete a custom role + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Update a permission tags: - - authorization - /authorization/organizations/{organizationId}/roles/{slug}/permissions: - put: - description: Replace all permissions on a custom role with the provided list. - operationId: AuthorizationOrganizationRolePermissionsController_setPermissions + - permissions + delete: + description: Delete an existing permission. System permissions cannot be deleted. + operationId: AuthorizationPermissionsController_delete 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. + 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 - example: org-admin - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/SetRolePermissionsDto' responses: - '200': - description: OK + '204': + description: No Content + '403': + description: Forbidden 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 + message: type: string - description: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true - '403': - description: Forbidden + - message + '404': + description: Not Found content: application/json: schema: @@ -3589,8 +6288,137 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '404': - description: Not Found + summary: Delete a permission + tags: + - permissions + /authorization/resources: + get: + description: Get a paginated list of authorization resources. + operationId: AuthorizationResourcesController_list + parameters: + - name: before + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `before="obj_123"` to fetch a new batch + of objects before `"obj_123"`. + schema: + example: xxx_01HXYZ123456789ABCDEFGHIJ + type: string + - name: after + required: false + in: query + description: >- + An object ID that defines your place in the list. When the ID is not + present, you are at the end of the list. For example, if you make a + list request and receive 100 objects, ending with `"obj_123"`, your + subsequent call can include `after="obj_123"` to fetch a new batch + of objects after `"obj_123"`. + schema: + example: xxx_01HXYZ987654321KJIHGFEDCBA + type: string + - name: limit + required: false + in: query + description: >- + Upper limit on the number of objects to return, between `1` and + `100`. + schema: + minimum: 1 + maximum: 100 + default: 10 + example: 10 + type: integer + - name: order + required: false + in: query + description: >- + Order the results by the creation time. Supported values are `"asc"` + (ascending), `"desc"` (descending), and `"normal"` (descending with + reversed cursor semantics where `before` fetches older records and + `after` fetches newer records). Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - 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 + 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: missing_organization_id_or_resource_type_slug + const: missing_organization_id_or_resource_type_slug + 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: @@ -3615,86 +6443,74 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Set permissions for a custom role + summary: List resources 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: - description: >- - Add a single permission to a custom role. If the permission is already - assigned to the role, this operation has no effect. - operationId: AuthorizationOrganizationRolePermissionsController_addPermission - 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 + description: Create a new authorization resource. + operationId: AuthorizationResourcesController_create + parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/AddRolePermissionDto' + $ref: '#/components/schemas/CreateAuthorizationResourceDto' responses: - '200': - description: OK + '201': + description: Created 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 + description: Distinguishes the Resource object. + const: authorization_resource name: type: string - description: A descriptive name for the role. - example: Organization Admin + description: A human-readable name for the Resource. + example: Acme Workspace description: type: - string - 'null' - description: An optional description of the role. - example: Can manage all resources - type: + 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 - enum: - - EnvironmentRole - - OrganizationRole description: >- - Whether the role is scoped to the environment or an - organization (custom role). - example: OrganizationRole + 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 the role is scoped to. - example: organization - permissions: - type: array - items: - type: string - description: The permission slugs assigned to the role. - example: - - reports:export + description: The slug of the resource type this resource belongs to. + example: workspace created_at: format: date-time type: string @@ -3706,14 +6522,14 @@ paths: description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: - - slug - object - - id - name - description - - type + - organization_id + - parent_resource_id + - id + - external_id - resource_type_slug - - permissions - created_at - updated_at x-inline-with-overrides: true @@ -3722,20 +6538,35 @@ paths: 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 + 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: @@ -3762,6 +6593,40 @@ paths: 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: @@ -3775,42 +6640,37 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Add a permission to a custom role + summary: Create an authorization resource tags: - authorization - /authorization/organizations/{organizationId}/roles/{slug}/permissions/{permissionSlug}: - delete: - description: Remove a single permission from a custom role by its slug. - operationId: AuthorizationOrganizationRolePermissionsController_removePermission + 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: + description: Retrieve the details of an authorization resource by its ID. + operationId: AuthorizationResourcesController_findById 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 + - name: resource_id required: true in: path - description: The slug of the permission to remove. + description: The ID of the authorization resource. schema: type: string - example: documents:read + example: authz_resource_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/Role' + $ref: '#/components/schemas/AuthorizationResource' '403': description: Forbidden content: @@ -3837,61 +6697,8 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Remove a permission from a custom role - tags: - - authorization - /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}: - get: - 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. - operationId: AuthorizationResourcesByExternalIdController_getByExternalId - 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 + '422': + description: Unprocessable Entity content: application/json: schema: @@ -3903,34 +6710,20 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get a resource by external ID + summary: Get a resource tags: - authorization patch: - description: Update an existing authorization resource using its external ID. - operationId: AuthorizationResourcesByExternalIdController_updateByExternalId + description: Update an existing authorization resource. + operationId: AuthorizationResourcesController_update 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 + - name: resource_id required: true in: path - description: An identifier you provide to reference the resource in your system. + description: The ID of the authorization resource. schema: type: string - example: proj-456 + example: authz_resource_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: @@ -4082,45 +6875,21 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Update a resource by external ID + summary: Update a resource 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 + x-mutually-exclusive-body-groups: *ref_0 delete: - description: >- - Delete an authorization resource by organization, resource type, and - external ID. This also deletes all descendant resources. - operationId: AuthorizationResourcesByExternalIdController_deleteByExternalId + description: Delete an authorization resource and all its descendants. + operationId: AuthorizationResourcesController_delete 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 + - name: resource_id required: true in: path - description: An identifier you provide to reference the resource in your system. + description: The ID of the authorization resource. schema: type: string - example: proj-456 + example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: cascade_delete required: false in: query @@ -4214,40 +6983,24 @@ paths: required: - code - message - summary: Delete an authorization resource by external ID + summary: Delete an authorization resource tags: - authorization - /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/organization_memberships: + /authorization/resources/{resource_id}/organization_memberships: get: 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. - operationId: >- - AuthorizationResourcesByExternalIdController_listOrganizationMembershipsForResourceByExternalId + a resource instance. This is useful for answering "Who can access this + resource?". + operationId: AuthorizationResourcesController_listOrganizationMembershipsForResource 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 + - name: resource_id required: true in: path - description: An identifier you provide to reference the resource in your system. + description: The ID of the authorization resource. schema: - example: proj-456 type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query @@ -4302,13 +7055,13 @@ paths: the resource are returned. schema: type: string - example: project:read + 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. + Filter by assignment type. Use `direct` for direct assignments only, + or `indirect` to include inherited assignments. schema: type: string enum: @@ -4381,133 +7134,23 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List memberships for a resource by external ID + summary: List organization memberships for resource tags: - authorization - /authorization/organizations/{organization_id}/resources/{resource_type_slug}/{external_id}/role_assignments: + /authorization/resources/{resource_id}/role_assignments: get: description: >- - List all role assignments granted on a resource, identified by its - external ID. Each assignment includes the organization membership it was - granted to. - operationId: >- - AuthorizationRoleAssignmentsController_listRoleAssignmentsForResourceByExternalId + List all role assignments granted on a specific resource instance. Each + assignment includes the organization membership it was granted to. + operationId: AuthorizationRoleAssignmentsController_listRoleAssignmentsForResource 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 + - name: resource_id required: true in: path - description: An identifier you provide to reference the resource in your system. - schema: - type: string - example: proj-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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - name: role_slug - required: false - in: query - description: Filter assignments by the slug of the role. + description: The ID of the authorization resource. schema: - example: editor - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserRoleAssignmentList' - '403': - description: Forbidden - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - '404': - description: Not Found - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: List role assignments for a resource by external ID - tags: - - authorization - /authorization/permissions: - get: - description: Get a list of all permissions in your WorkOS environment. - operationId: AuthorizationPermissionsController_list - parameters: + type: string + example: authz_resource_01HXYZ123456789ABCDEFGHIJ - name: before required: false in: query @@ -4554,13 +7197,33 @@ paths: `after` fetches newer records). Defaults to `normal`. schema: $ref: '#/components/schemas/PaginationOrder' + - name: role_slug + required: false + in: query + description: Filter assignments by the slug of the role. + schema: + example: editor + type: string responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationPermissionList' + $ref: '#/components/schemas/UserRoleAssignmentList' + '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: @@ -4574,21 +7237,20 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List permissions + summary: List role assignments for a resource tags: - - permissions + - authorization + /authorization/roles: post: - description: >- - Create a new permission in your WorkOS environment. The permission can - then be assigned to environment roles and custom roles. - operationId: AuthorizationPermissionsController_create + description: Create a new environment role. + operationId: AuthorizationRolesController_create parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateAuthorizationPermissionDto' + $ref: '#/components/schemas/CreateRoleDto' responses: '201': description: Created @@ -4597,43 +7259,50 @@ paths: schema: type: object properties: + slug: + type: string + description: A unique slug for the role. + example: editor object: type: string - description: Distinguishes the Permission object. - const: permission + description: Distinguishes the role object. + example: role + const: role 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 + description: Unique identifier of the role. + example: role_01EHQMYV6MBK39QC5PZXHY59C3 name: type: string - description: A descriptive name for the Permission. - example: View Documents + description: A descriptive name for the role. + example: Editor description: type: - string - 'null' - description: An optional description of the Permission. - example: Allows viewing document contents - system: - type: boolean + description: An optional description of the role. + example: Can edit resources + type: + type: string + enum: + - EnvironmentRole + - OrganizationRole description: >- - Whether the permission is a system permission. System - permissions are managed by WorkOS and cannot be deleted. - example: false + 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 associated with the - permission. - example: document + 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 @@ -4645,13 +7314,14 @@ paths: description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: + - slug - object - id - - slug - name - description - - system + - type - resource_type_slug + - permissions - created_at - updated_at x-inline-with-overrides: true @@ -4674,6 +7344,19 @@ paths: 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: @@ -4697,8 +7380,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: permission_slug_conflict - const: permission_slug_conflict + example: role_slug_conflict + const: role_slug_conflict message: type: string description: A human-readable description of the error. @@ -4719,33 +7402,22 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Create a permission + summary: Create an environment role tags: - - permissions - /authorization/permissions/{slug}: + - authorization get: - description: Retrieve a permission by its unique slug. - operationId: AuthorizationPermissionsController_find - 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 + description: List all environment roles in priority order. + operationId: AuthorizationRolesController_list + parameters: [] responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationPermission' - '404': - description: Not Found + $ref: '#/components/schemas/RoleList' + '403': + description: Forbidden content: application/json: schema: @@ -4757,38 +7429,28 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get a permission + summary: List environment roles tags: - - permissions - patch: - description: >- - Update an existing permission. Only the fields provided in the request - body will be updated. - operationId: AuthorizationPermissionsController_update + - authorization + /authorization/roles/{slug}: + get: + description: Get an environment role by its slug. + operationId: AuthorizationRolesController_get 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. + description: The slug of the environment role. schema: - example: documents:read type: string - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAuthorizationPermissionDto' + example: admin responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationPermission' + $ref: '#/components/schemas/Role' '403': description: Forbidden content: @@ -4815,39 +7477,119 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity + summary: Get an environment role + tags: + - authorization + patch: + description: Update an existing environment role. + operationId: AuthorizationRolesController_update + 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: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - summary: Update a permission - tags: - - permissions - delete: - description: Delete an existing permission. System permissions cannot be deleted. - operationId: AuthorizationPermissionsController_delete - 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: @@ -4874,116 +7616,116 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Delete a permission + '422': + description: Unprocessable Entity + content: + application/json: + schema: + type: object + properties: + message: + type: string + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + required: + - message + summary: Update an environment role tags: - - permissions - /authorization/resources: - get: - description: Get a paginated list of authorization resources. - operationId: AuthorizationResourcesController_list + - authorization + /authorization/roles/{slug}/permissions: + put: + description: Replace all permissions on an environment role with the provided list. + operationId: AuthorizationRolePermissionsController_setPermissions 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - 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`. + - name: slug + required: true + in: path + description: The slug of the environment role. schema: type: string - example: ext-workspace-123 + example: admin + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SetRolePermissionsDto' responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/AuthorizationResourceList' + 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: @@ -4994,8 +7736,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: missing_organization_id_or_resource_type_slug - const: missing_organization_id_or_resource_type_slug + example: bad_request + const: bad_request message: type: string description: A human-readable description of the error. @@ -5016,6 +7758,19 @@ paths: 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: @@ -5029,74 +7784,79 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List resources + summary: Set permissions for an environment role 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: - description: Create a new authorization resource. - operationId: AuthorizationResourcesController_create - parameters: [] + description: >- + Add a single permission to an environment role. If the permission is + already assigned to the role, this operation has no effect. + operationId: AuthorizationRolePermissionsController_addPermission + 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/CreateAuthorizationResourceDto' + $ref: '#/components/schemas/AddRolePermissionDto' responses: - '201': - description: Created + '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 Resource object. - const: authorization_resource + 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 human-readable name for the Resource. - example: Acme Workspace + description: A descriptive name for the role. + example: Admin 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: + description: An optional description of the role. + example: Can manage all resources + type: type: string + enum: + - EnvironmentRole + - OrganizationRole description: >- - An identifier you provide to reference the resource in - your system. - example: my-workspace-01 + 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 this resource belongs to. - example: workspace + 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 @@ -5108,14 +7868,14 @@ paths: description: An ISO 8601 timestamp. example: '2026-01-15T12:00:00.000Z' required: + - slug - object + - id - name - description - - organization_id - - parent_resource_id - - id - - external_id + - type - resource_type_slug + - permissions - created_at - updated_at x-inline-with-overrides: true @@ -5124,35 +7884,20 @@ paths: 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 + 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: @@ -5179,40 +7924,6 @@ paths: 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: @@ -5226,39 +7937,31 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Create an authorization resource + summary: Add a permission to an environment role 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: - description: Retrieve the details of an authorization resource by its ID. - operationId: AuthorizationResourcesController_findById - parameters: - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. - schema: - type: string - example: authz_resource_01HXYZ123456789ABCDEFGHIJ + /client/token: + post: + description: >- + Generate a short-lived, session-bound token for the Client GraphQL API, + scoped to an organization and user. + operationId: ClientApiTokenController_issueClientApiToken + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ClientApiTokenDto' responses: - '200': - description: OK + '201': + description: Created content: application/json: schema: - $ref: '#/components/schemas/AuthorizationResource' - '403': - description: Forbidden + $ref: '#/components/schemas/ClientApiTokenResponse' + '400': + description: Bad Request content: application/json: schema: @@ -5296,126 +7999,132 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get a resource + summary: Generate a Client API token tags: - - authorization - patch: - description: Update an existing authorization resource. - operationId: AuthorizationResourcesController_update + - client + /connect/applications: + get: + description: >- + List all Connect Applications in the current environment with optional + filtering. + operationId: ApplicationsController_list parameters: - - name: resource_id - required: true - in: path - description: The ID of the authorization resource. + - 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 - example: authz_resource_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateAuthorizationResourceDto' + - 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 `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - name: registration_types + required: false + in: query + description: >- + Filter Connect Applications by registration type. Specify multiple + as a comma-separated list (e.g. + `registration_types=dynamic,authenticated`). Defaults to + `authenticated` only when not specified. + style: form + explode: false + schema: + type: array + items: + type: string + enum: + - dynamic + - authenticated + example: + - authenticated + - 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: - 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 + $ref: '#/components/schemas/ConnectApplicationList' + '422': + description: Unprocessable Entity 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. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - '403': - description: Forbidden + summary: List Connect Applications + tags: + - applications + post: + description: >- + Create a new Connect Application. Supports both OAuth and + Machine-to-Machine (M2M) application types. + operationId: ApplicationsController_create + 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: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message + $ref: '#/components/schemas/ConnectApplication' '404': description: Not Found content: @@ -5429,27 +8138,43 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '409': - description: '' + '422': + description: Unprocessable Entity 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. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - '422': - description: Unprocessable Entity + summary: Create a Connect Application + tags: + - applications + /connect/applications/{id}: + get: + description: Retrieve details for a specific Connect Application by ID or client ID. + operationId: ApplicationsController_find + 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: @@ -5461,56 +8186,51 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Update a resource + summary: Get a Connect Application tags: - - authorization - x-mutually-exclusive-body-groups: *ref_0 - delete: - description: Delete an authorization resource and all its descendants. - operationId: AuthorizationResourcesController_delete + - applications + put: + 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. + operationId: ApplicationsController_update parameters: - - name: resource_id + - name: id required: true in: path - description: The ID of the authorization resource. + description: The application ID or client ID of the Connect Application. 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 + example: conn_app_01HXYZ123456789ABCDEFGHIJ + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOAuthApplicationDto' responses: - '204': - description: No Content - '400': - description: Bad Request + '200': + description: OK 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 + $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: Request could not be processed. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - '403': - description: Forbidden + '422': + description: Unprocessable Entity content: application/json: schema: @@ -5522,6 +8242,23 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message + summary: Update a Connect Application + tags: + - applications + delete: + description: Delete an existing Connect Application. + operationId: ApplicationsController_delete + 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: @@ -5535,165 +8272,111 @@ paths: 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 - summary: Delete an authorization resource + summary: Delete a Connect Application tags: - - authorization - /authorization/resources/{resource_id}/organization_memberships: + - applications + /connect/applications/{id}/client_secrets: get: - description: >- - Returns all organization memberships that have a specific permission on - a resource instance. This is useful for answering "Who can access this - resource?". - operationId: AuthorizationResourcesController_listOrganizationMembershipsForResource + description: List all client secrets associated with a Connect Application. + operationId: ApplicationCredentialsController_list parameters: - - name: resource_id + - name: 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - 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. + description: The application ID or client ID of the Connect Application. schema: type: string - enum: - - direct - - indirect - example: direct + example: conn_app_01HXYZ123456789ABCDEFGHIJ responses: '200': description: OK content: application/json: schema: - $ref: >- - #/components/schemas/UserlandUserOrganizationMembershipBaseWithUserList - '400': - description: Bad Request + 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: + format: date-time + 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: - 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. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - code - message - '403': - description: Forbidden + summary: List Client Secrets for a Connect Application + tags: + - application.client-secrets + post: + description: Create new secrets for a Connect Application. + operationId: ApplicationCredentialsController_create + 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: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message + $ref: '#/components/schemas/NewConnectApplicationSecret' '404': description: Not Found content: @@ -5720,96 +8403,24 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List organization memberships for resource + summary: Create a new client secret for a Connect Application tags: - - authorization - /authorization/resources/{resource_id}/role_assignments: - get: - description: >- - List all role assignments granted on a specific resource instance. Each - assignment includes the organization membership it was granted to. - operationId: AuthorizationRoleAssignmentsController_listRoleAssignmentsForResource + - application.client-secrets + /connect/client_secrets/{id}: + delete: + description: Delete (revoke) an existing client secret. + operationId: ApplicationCredentialsController_delete parameters: - - name: resource_id + - name: 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - name: role_slug - required: false - in: query - description: Filter assignments by the slug of the role. + description: The unique ID of the client secret. schema: - example: editor type: string + example: secret_01J9Q2Z3X4Y5W6V7U8T9S0R1Q responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/UserRoleAssignmentList' - '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 + '204': + description: No Content '404': description: Not Found content: @@ -5823,113 +8434,247 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List role assignments for a resource + summary: Delete a Client Secret tags: - - authorization - /authorization/roles: + - application.client-secrets + /connections: post: - description: Create a new environment role. - operationId: AuthorizationRolesController_create + description: >- + Creates a new connection for an organization. Provide `saml_options` or + `oidc_options` to configure the identity provider. When `external_id` + matches an existing connection in the organization, that connection is + returned instead of creating a duplicate. + operationId: ConnectionsController_create parameters: [] requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateRoleDto' + $ref: '#/components/schemas/CreateConnectionDto' 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 + $ref: '#/components/schemas/Connection' '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 + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_id_already_in_use + const: external_id_already_in_use + 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: connection_type_not_supported + const: connection_type_not_supported + 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: connection_type_or_options_required + const: connection_type_or_options_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: connection_type_conflicts_with_options + const: connection_type_conflicts_with_options + 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: both_saml_and_oidc_options_provided + const: both_saml_and_oidc_options_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: ambiguous_saml_options + const: ambiguous_saml_options + 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: incomplete_saml_options + const: incomplete_saml_options + 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: saml_options_required + const: saml_options_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: oidc_options_required + const: oidc_options_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: invalid_certificate + const: invalid_certificate + 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: client_secret_required + const: client_secret_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: client_secret_not_accepted + const: client_secret_not_accepted + 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: key_pair_not_accepted + const: key_pair_not_accepted + 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: discovery_endpoint_must_use_https + const: discovery_endpoint_must_use_https + 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: token_authentication_method_not_supported + const: token_authentication_method_not_supported + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message '403': description: Forbidden content: @@ -5966,8 +8711,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: role_slug_conflict - const: role_slug_conflict + example: connection_deletion_in_progress + const: connection_deletion_in_progress message: type: string description: A human-readable description of the error. @@ -5980,63 +8725,196 @@ paths: content: application/json: schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: Create an environment role - tags: - - authorization - get: - description: List all environment roles in priority order. - operationId: AuthorizationRolesController_list - 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 - summary: List environment roles + 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: + code: + type: string + description: The error code identifying the type of error. + example: idp_metadata_fetch_failed + const: idp_metadata_fetch_failed + 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: connection_could_not_be_verified + const: connection_could_not_be_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_idp_sso_url + const: invalid_idp_sso_url + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + summary: Create a Connection tags: - - authorization - /authorization/roles/{slug}: + - connections + x-feature-flag: connections-api-migrations-capabilities-api + x-mutually-exclusive-body-groups: &ref_7 + protocol_options: + optional: false + variants: + saml: + - saml_options + oidc: + - oidc_options get: - description: Get an environment role by its slug. - operationId: AuthorizationRolesController_get + description: >- + Get a list of all of your existing connections matching the criteria + specified. + operationId: ConnectionsController_list parameters: - - name: slug - required: true - in: path - description: The slug of the environment role. + - 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. Defaults to `normal`. + schema: + $ref: '#/components/schemas/PaginationOrder' + - 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 + - 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 - example: admin responses: '200': description: OK content: application/json: schema: - $ref: '#/components/schemas/Role' + $ref: '#/components/schemas/ConnectionList' '403': description: Forbidden content: @@ -6050,8 +8928,8 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '404': - description: Not Found + '422': + description: Unprocessable Entity content: application/json: schema: @@ -6063,100 +8941,30 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get an environment role + summary: List Connections tags: - - authorization - patch: - description: Update an existing environment role. - operationId: AuthorizationRolesController_update + - connections + /connections/{connectionId}/saml_idp_signing_certs: + get: + description: >- + Lists every Identity Provider signing certificate on the connection, + including expired ones, oldest first. + operationId: SamlIdpSigningCertificatesController_list parameters: - - name: slug + - name: connectionId required: true in: path - description: The slug of the environment role. + description: Unique identifier for the Connection. schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 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 + $ref: '#/components/schemas/SamlIdpSigningCertificateList' '400': description: Bad Request content: @@ -6167,8 +8975,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: bad_request - const: bad_request + example: connection_is_not_saml + const: connection_is_not_saml message: type: string description: A human-readable description of the error. @@ -6202,116 +9010,155 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: Update an environment role + summary: List IdP signing certificates tags: - - authorization - /authorization/roles/{slug}/permissions: - put: - description: Replace all permissions on an environment role with the provided list. - operationId: AuthorizationRolePermissionsController_setPermissions + - connections + x-feature-flag: connections-api-migrations-capabilities-api + post: + description: >- + Adds an Identity Provider signing certificate to the connection, so SAML + responses signed with its key can be verified. Use this to import a new + certificate ahead of an Identity Provider rotation — the existing + certificates keep working until they are deleted or expire. + operationId: SamlIdpSigningCertificatesController_create parameters: - - name: slug + - name: connectionId required: true in: path - description: The slug of the environment role. + description: Unique identifier for the Connection. schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 type: string - example: admin requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/SetRolePermissionsDto' + $ref: '#/components/schemas/CreateSamlIdpSigningCertificateDto' responses: - '200': - description: OK + '201': + description: Created 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: + $ref: '#/components/schemas/SamlIdpSigningCertificate' + '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: connection_is_not_saml + const: connection_is_not_saml + 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_certificate + const: invalid_certificate + 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: certificate_expired + const: certificate_expired + 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: 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 + 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: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' - updated_at: - format: date-time + 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: An ISO 8601 timestamp. - example: '2026-01-15T12:00:00.000Z' + description: A human-readable description of the error. + example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - - slug - - object - - id - - name - - description - - type - - resource_type_slug - - permissions - - created_at - - updated_at - x-inline-with-overrides: true + - message + summary: Create an IdP signing certificate + tags: + - connections + x-feature-flag: connections-api-migrations-capabilities-api + /connections/{connectionId}/saml_idp_signing_certs/{certificateId}: + delete: + description: >- + Removes an Identity Provider signing certificate from the connection. + The last remaining certificate cannot be deleted. A certificate still + published in the Identity Provider metadata may be restored by a + metadata refresh. + operationId: SamlIdpSigningCertificatesController_delete + parameters: + - name: connectionId + required: true + in: path + description: Unique identifier for the Connection. + schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - name: certificateId + required: true + in: path + description: Unique identifier for the Identity Provider signing certificate. + schema: + example: saml_x509_cert_01E4ZCR3C56J083X43JQXF3JK5 + type: string + responses: + '204': + description: No Content '400': description: Bad Request content: @@ -6322,8 +9169,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: bad_request - const: bad_request + example: cannot_delete_last_certificate + const: cannot_delete_last_certificate message: type: string description: A human-readable description of the error. @@ -6357,114 +9204,31 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: Set permissions for an environment role + summary: Delete an IdP signing certificate tags: - - authorization - post: + - connections + x-feature-flag: connections-api-migrations-capabilities-api + /connections/{connectionId}/saml_sp_encryption_certs: + get: description: >- - Add a single permission to an environment role. If the permission is - already assigned to the role, this operation has no effect. - operationId: AuthorizationRolePermissionsController_addPermission + Lists the public certificates the Identity Provider can use to encrypt + SAML responses sent to WorkOS, including expired ones, oldest first. + operationId: SamlSpEncryptionCertificatesController_list parameters: - - name: slug + - name: connectionId required: true in: path - description: The slug of the environment role. + description: Unique identifier for the Connection. schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 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 + $ref: '#/components/schemas/SamlSpEncryptionCertificateList' '400': description: Bad Request content: @@ -6475,8 +9239,8 @@ paths: code: type: string description: The error code identifying the type of error. - example: bad_request - const: bad_request + example: connection_is_not_saml + const: connection_is_not_saml message: type: string description: A human-readable description of the error. @@ -6510,44 +9274,71 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity - content: - application/json: - schema: - type: object - properties: - message: - type: string - description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' - required: - - message - summary: Add a permission to an environment role + summary: List SP encryption certificates tags: - - authorization - /client/token: + - connections + x-feature-flag: connections-api-migrations-capabilities-api post: description: >- - Generate a short-lived, session-bound token for the Client GraphQL API, - scoped to an organization and user. - operationId: ClientApiTokenController_issueClientApiToken - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/ClientApiTokenDto' + Generates a new encryption key pair for the connection and returns its + public certificate. WorkOS holds the private key, so the request takes + no body — to bring your own key pairs, provide + `saml_options.sp_encryption_key_pairs` when creating the connection + instead. Creating a certificate appends rather than replaces: every + active private key is tried when decrypting, which lets a rotation + overlap the old and new certificates. + operationId: SamlSpEncryptionCertificatesController_create + parameters: + - name: connectionId + required: true + in: path + description: Unique identifier for the Connection. + schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + type: string responses: '201': description: Created content: application/json: schema: - $ref: '#/components/schemas/ClientApiTokenResponse' + $ref: '#/components/schemas/SamlSpEncryptionCertificate' '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: connection_is_not_saml + const: connection_is_not_saml + 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: key_pair_not_accepted + const: key_pair_not_accepted + 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: @@ -6572,110 +9363,90 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity + '409': + description: '' content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: too_many_sp_encryption_certs + const: too_many_sp_encryption_certs message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - summary: Generate a Client API token + '503': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: concurrent_request + const: concurrent_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + summary: Create an SP encryption certificate tags: - - client - /connect/applications: - get: + - connections + x-feature-flag: connections-api-migrations-capabilities-api + /connections/{connectionId}/saml_sp_encryption_certs/{certificateId}: + delete: description: >- - List all Connect Applications in the current environment with optional - filtering. - operationId: ApplicationsController_list + Removes an encryption key pair from the connection. SAML responses + encrypted with its certificate can no longer be decrypted, so remove the + certificate from the Identity Provider first when rotating. + operationId: SamlSpEncryptionCertificatesController_delete 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"`. + - name: connectionId + required: true + in: path + description: Unique identifier for the Connection. schema: - example: xxx_01HXYZ987654321KJIHGFEDCBA + example: conn_01E4ZCR3C56J083X43JQXF3JK5 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 `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - name: registration_types - required: false - in: query + - name: certificateId + required: true + in: path description: >- - Filter Connect Applications by registration type. Specify multiple - as a comma-separated list (e.g. - `registration_types=dynamic,authenticated`). Defaults to - `authenticated` only when not specified. - style: form - explode: false - schema: - type: array - items: - type: string - enum: - - dynamic - - authenticated - example: - - authenticated - - name: organization_id - required: false - in: query - description: Filter Connect Applications by organization ID. + Unique identifier for the Service Provider encryption key pair. + WorkOS holds the corresponding private key, which is never exposed. schema: + example: saml_enc_key_pair_01E4ZCR3C56J083X43JQXF3JK5 type: string - example: org_01EHZNVPK3SFK441A1RGBFSHRT responses: - '200': - description: OK + '204': + description: No Content + '403': + description: Forbidden content: application/json: schema: - $ref: '#/components/schemas/ConnectApplicationList' - '422': - description: Unprocessable Entity + 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: @@ -6687,45 +9458,53 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List Connect Applications + summary: Delete an SP encryption certificate tags: - - applications - post: + - connections + x-feature-flag: connections-api-migrations-capabilities-api + /connections/{connectionId}/saml_sp_signing_cert: + get: description: >- - Create a new Connect Application. Supports both OAuth and - Machine-to-Machine (M2M) application types. - operationId: ApplicationsController_create - parameters: [] - requestBody: - required: true - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/CreateOAuthApplicationDto' - - $ref: '#/components/schemas/CreateM2MApplicationDto' + Returns the public certificate the Identity Provider can use to verify + the signature of SAML requests sent by WorkOS. Responds with `404` when + the connection has no request signing key pair. + operationId: SamlSpSigningCertificatesController_get + parameters: + - name: connectionId + required: true + in: path + description: Unique identifier for the Connection. + schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + type: string responses: - '201': - description: Created + '200': + description: OK content: application/json: schema: - $ref: '#/components/schemas/ConnectApplication' - '404': - description: Not Found + $ref: '#/components/schemas/SamlSpSigningCertificate' + '400': + description: Bad Request content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: connection_is_not_saml + const: connection_is_not_saml message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - '422': - description: Unprocessable Entity + '403': + description: Forbidden content: application/json: schema: @@ -6737,28 +9516,6 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Create a Connect Application - tags: - - applications - /connect/applications/{id}: - get: - description: Retrieve details for a specific Connect Application by ID or client ID. - operationId: ApplicationsController_find - 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: @@ -6772,36 +9529,95 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Get a Connect Application + summary: Get the SP signing certificate tags: - - applications - put: + - connections + x-feature-flag: connections-api-migrations-capabilities-api + post: 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. - operationId: ApplicationsController_update + Generates a new request signing key pair for the connection and returns + its public certificate. WorkOS holds the private key, so the request + takes no body — to bring your own key pair, provide + `saml_options.sp_signing_key_pair` when creating the connection instead. + A connection signs with one key pair at a time: delete the existing + certificate before creating its replacement. + operationId: SamlSpSigningCertificatesController_create parameters: - - name: id + - name: connectionId required: true in: path - description: The application ID or client ID of the Connect Application. + description: Unique identifier for the Connection. schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateOAuthApplicationDto' responses: - '200': - description: OK + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/SamlSpSigningCertificate' + '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: connection_is_not_saml + const: connection_is_not_saml + 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: key_pair_not_accepted + const: key_pair_not_accepted + 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: connection_type_not_supported + const: connection_type_not_supported + 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: - $ref: '#/components/schemas/ConnectApplication' + 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: @@ -6815,38 +9631,77 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - '422': - description: Unprocessable Entity + '409': + description: '' content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: sp_signing_cert_already_exists + const: sp_signing_cert_already_exists message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + example: Request could not be processed. required: + - code - message - summary: Update a Connect Application + '503': + description: '' + content: + application/json: + schema: + type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: concurrent_request + const: concurrent_request + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + summary: Create an SP signing certificate tags: - - applications + - connections + x-feature-flag: connections-api-migrations-capabilities-api + /connections/{connectionId}/saml_sp_signing_cert/{certificateId}: delete: - description: Delete an existing Connect Application. - operationId: ApplicationsController_delete + description: >- + Removes the request signing key pair from the connection, after which + SAML requests are sent unsigned. Delete the certificate before creating + its replacement when rotating. + operationId: SamlSpSigningCertificatesController_delete parameters: - - name: id + - name: connectionId required: true in: path - description: The application ID or client ID of the Connect Application. + description: Unique identifier for the Connection. schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 + type: string + - name: certificateId + required: true + in: path + description: >- + Unique identifier for the Service Provider signing key pair. WorkOS + holds the corresponding private key, which is never exposed. + schema: + example: saml_party_trust_01E4ZCR3C56J083X43JQXF3JK5 type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ responses: '204': description: No Content - '404': - description: Not Found + '403': + description: Forbidden content: application/json: schema: @@ -6858,71 +9713,6 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Delete a Connect Application - tags: - - applications - /connect/applications/{id}/client_secrets: - get: - description: List all client secrets associated with a Connect Application. - operationId: ApplicationCredentialsController_list - 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: - format: date-time - 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: @@ -6936,48 +9726,185 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: List Client Secrets for a Connect Application + summary: Delete the SP signing certificate tags: - - application.client-secrets - post: - description: Create new secrets for a Connect Application. - operationId: ApplicationCredentialsController_create + - connections + x-feature-flag: connections-api-migrations-capabilities-api + /connections/{id}: + patch: + description: >- + Updates an existing connection. Only the provided fields are changed; + fields that accept `null` are reset to their default behavior. + operationId: ConnectionsController_patch parameters: - name: id required: true in: path - description: The application ID or client ID of the Connect Application. + description: Unique identifier for the Connection. schema: + example: conn_01E4ZCR3C56J083X43JQXF3JK5 type: string - example: conn_app_01HXYZ123456789ABCDEFGHIJ requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateApplicationSecretDto' + $ref: '#/components/schemas/PatchConnectionDto' responses: - '201': - description: Created + '200': + description: OK content: application/json: schema: - $ref: '#/components/schemas/NewConnectApplicationSecret' - '404': - description: Not Found + $ref: '#/components/schemas/Connection' + '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 + oneOf: + - type: object + properties: + code: + type: string + description: The error code identifying the type of error. + example: external_id_already_in_use + const: external_id_already_in_use + 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: connection_type_not_supported + const: connection_type_not_supported + 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: connection_type_conflicts_with_options + const: connection_type_conflicts_with_options + 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: both_saml_and_oidc_options_provided + const: both_saml_and_oidc_options_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: ambiguous_saml_options + const: ambiguous_saml_options + 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: token_authentication_method_not_supported + const: token_authentication_method_not_supported + 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: id_token_signature_algorithm_not_supported + const: id_token_signature_algorithm_not_supported + 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: client_secret_required + const: client_secret_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: client_secret_not_accepted + const: client_secret_not_accepted + 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: discovery_endpoint_must_use_https + const: discovery_endpoint_must_use_https + 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: @@ -6989,24 +9916,6 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Create a new client secret for a Connect Application - tags: - - application.client-secrets - /connect/client_secrets/{id}: - delete: - description: Delete (revoke) an existing client secret. - operationId: ApplicationCredentialsController_delete - 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: @@ -7020,165 +9929,95 @@ paths: example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' required: - message - summary: Delete a Client Secret - tags: - - application.client-secrets - /connections: - get: - description: >- - Get a list of all of your existing connections matching the criteria - specified. - operationId: ConnectionsController_list - parameters: - - name: before - required: false - in: query - description: >- - An object ID that defines your place in the list. When the ID is not - present, you are at the end of the list. - 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. Defaults to `normal`. - schema: - $ref: '#/components/schemas/PaginationOrder' - - 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 - - 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 + '409': + description: '' content: application/json: schema: type: object properties: + code: + type: string + description: The error code identifying the type of error. + example: connection_deletion_in_progress + const: connection_deletion_in_progress message: type: string description: A human-readable description of the error. - example: 'Organization not found: ''org_01EHQMYV6MBK39QC5PZXHY59C3''.' + 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 - summary: List Connections + 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: + code: + type: string + description: The error code identifying the type of error. + example: connection_type_not_updatable + const: connection_type_not_updatable + 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: idp_metadata_fetch_failed + const: idp_metadata_fetch_failed + 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: connection_could_not_be_verified + const: connection_could_not_be_verified + message: + type: string + description: A human-readable description of the error. + example: Request could not be processed. + required: + - code + - message + summary: Update a Connection tags: - connections - /connections/{id}: + x-feature-flag: connections-api-migrations-capabilities-api + x-mutually-exclusive-body-groups: &ref_10 + protocol_options: + optional: true + variants: + saml: + - saml_options + oidc: + - oidc_options get: description: Get the details of an existing connection. operationId: ConnectionsController_find @@ -15777,7 +18616,7 @@ paths: summary: Create an organization membership tags: - user-management.organization-membership - x-mutually-exclusive-body-groups: &ref_10 + x-mutually-exclusive-body-groups: &ref_14 role: optional: true variants: @@ -15961,7 +18800,7 @@ paths: summary: Update an organization membership tags: - user-management.organization-membership - x-mutually-exclusive-body-groups: &ref_11 + x-mutually-exclusive-body-groups: &ref_15 role: optional: true variants: @@ -17281,7 +20120,7 @@ paths: summary: Create a user tags: - user-management.users - x-mutually-exclusive-body-groups: &ref_12 + x-mutually-exclusive-body-groups: &ref_16 password: optional: true variants: @@ -17574,7 +20413,7 @@ paths: summary: Update a user tags: - user-management.users - x-mutually-exclusive-body-groups: &ref_16 + x-mutually-exclusive-body-groups: &ref_20 password: optional: true variants: @@ -19440,8 +22279,11 @@ paths: /user_management/waitlist_entries/{id}: delete: description: >- - Removes the entry from the waitlist. An invitation created by approving - the entry stays valid, so revoke that invitation to withdraw access. + Remove the entry from the waitlist. Its email address can join again + unless a user with that email now exists in the environment. Deleting + the entry does not revoke an invitation created by approving it — + [revoke that invitation](/reference/authkit/invitation/revoke) + separately to withdraw access. operationId: WaitlistEntriesController_delete parameters: - name: id @@ -19473,8 +22315,20 @@ paths: /user_management/waitlist_entries/{id}/approve: post: description: >- - Approve a waitlist entry and send the resulting user invitation email. - Also reverses a denial: a denied entry can be approved. + Approve a waitlist entry, create an invitation for its email address, + and send the invitation email. Approving a denied entry reverses the + denial. The approval is saved even when the invitation steps fail, so + instead of retrying the approval, recover based on the outcome: + + + - `200` — the entry is approved. If invitation creation failed, no + invitation exists yet; [send](/reference/authkit/invitation/send) one. + + - `422` with code `invitation_email_not_sent` — the entry is approved + and an invitation exists, but its email was not sent; + [resend](/reference/authkit/invitation/resend) it. + + - `422` with code `invalid_state` — the entry was already approved. operationId: WaitlistEntriesController_approve parameters: - name: id @@ -19610,8 +22464,9 @@ paths: /user_management/waitlist_entries/{id}/deny: post: description: >- - Deny a pending waitlist entry. A denial can be reversed by approving the - entry. + Deny a pending waitlist entry. Denying an entry that is not pending + fails with the code `invalid_state`. A denial can be reversed by + approving the entry. operationId: WaitlistEntriesController_deny parameters: - name: id @@ -19730,7 +22585,10 @@ paths: - user-management.waitlists /user_management/waitlists: get: - description: Get a list of the waitlists in the environment. + description: >- + Get a list of the waitlists in the environment. All waitlists are + returned in a single response — this endpoint is not paginated, so the + `list_metadata` cursors are always `null`. operationId: WaitlistsController_list parameters: [] responses: @@ -19794,7 +22652,9 @@ paths: in: path description: >- The unique ID of the waitlist, or the literal `default` for the - environment's default waitlist. + environment's default waitlist. The default waitlist is created when + its first entry is added, so read requests for `default` return a + `404` until then. schema: type: string example: waitlist_01E4ZCR3C56J083X43JQXF3JK5 @@ -19831,7 +22691,9 @@ paths: in: path description: >- The unique ID of the waitlist, or the literal `default` for the - environment's default waitlist. + environment's default waitlist. The default waitlist is created when + its first entry is added, so read requests for `default` return a + `404` until then. schema: type: string example: waitlist_01E4ZCR3C56J083X43JQXF3JK5 @@ -19983,9 +22845,12 @@ paths: - user-management.waitlists post: description: >- - Add an email address to the waitlist. Creating an entry is idempotent - per email address: a request for an email address already on the - waitlist returns the existing entry. + Add an email address to the waitlist. Email addresses are normalized and + unique per environment: a request for an email address already on the + waitlist returns the existing entry unchanged (still with status `201`) + and does not send another confirmation email. If a user with the email + address already exists in the environment, the request fails with the + code `user_already_exists`. operationId: WaitlistsController_createEntry parameters: - name: id @@ -19993,10 +22858,11 @@ paths: in: path description: >- The unique ID of the waitlist, or the literal `default` for the - environment's default waitlist. + environment's default waitlist. Use `default` when adding the first + entry — the default waitlist is created automatically. schema: type: string - example: waitlist_01E4ZCR3C56J083X43JQXF3JK5 + example: default requestBody: required: true content: @@ -20894,8 +23760,16 @@ info: tags: - name: admin-portal description: Endpoints for the Admin Portal API. - - name: agents - description: Manage agents for environments. + - name: agents.blueprints + description: Manage agent blueprints. + - name: agents.blueprints.tokens + description: Mint and validate agent access tokens. + - name: agents.instances + description: Manage agent instances. + - name: agents.registrations + description: Register agents and validate agent credentials. + - name: agents.sessions + description: Manage agent instance sessions. - name: api_keys description: Manage API keys for environments. - name: application.client-secrets @@ -21111,6 +23985,13 @@ components: required: - external_auth_id - user + PaginationOrder: + type: string + enum: + - normal + - desc + - asc + example: desc ValidateApiKeyDto: type: object properties: @@ -21133,13 +24014,6 @@ components: expiration. example: '2030-01-01T00:00:00.000Z' format: date-time - PaginationOrder: - type: string - enum: - - normal - - desc - - asc - example: desc RedirectUriDto: type: object properties: @@ -22150,6 +25024,525 @@ components: required: - parent_resource_id x-mutually-exclusive-body-groups: *ref_6 + CreateConnectionKeyPairDto: + type: object + properties: + key: + type: string + description: The PEM-encoded private key. + example: |- + -----BEGIN PRIVATE KEY----- + MIIE... + -----END PRIVATE KEY----- + cert: + type: string + description: The PEM-encoded X.509 certificate for the key. + example: |- + -----BEGIN CERTIFICATE----- + MIIC... + -----END CERTIFICATE----- + required: + - key + - cert + CreateConnectionSamlOptionsDto: + type: object + properties: + idp_metadata_url: + type: string + format: uri + description: >- + The Identity Provider metadata URL. When provided, the IdP fields + and signing certificates are imported from the metadata document. + Mutually exclusive with the manual IdP fields. + example: https://idp.example.com/metadata.xml + acs_url: + type: string + format: uri + description: >- + A custom Assertion Consumer Service (ACS) URL override. When + omitted, the standard WorkOS-generated ACS URL is used. + example: https://example.auth0.com/login/callback?connection=123 + sp_entity_id: + type: string + description: >- + A custom Service Provider Entity ID (audience) override. When + omitted, the connection external key is used. + example: https://example.auth0.com/login/callback?connection=123 + idp_entity_id: + type: string + description: The Identity Provider Entity ID. + example: https://idp.example.com/entity + idp_sso_url: + type: string + format: uri + description: >- + The Identity Provider SSO URL. Required when configuring the + connection with manual IdP fields. + example: https://idp.example.com/sso + idp_signing_certs: + description: >- + The X.509 certificates used to verify signed SAML responses from the + Identity Provider. Required when configuring the connection with + manual IdP fields. + example: + - |- + -----BEGIN CERTIFICATE----- + MIIC... + -----END CERTIFICATE----- + type: array + items: + type: string + sp_signing_key_pair: + description: >- + The customer-owned key pair used to sign SAML requests sent to the + Identity Provider. When omitted, WorkOS generates and manages the + signing key pair. + $ref: '#/components/schemas/CreateConnectionKeyPairDto' + sp_encryption_key_pairs: + description: >- + The customer-owned key pairs used to decrypt encrypted SAML + responses from the Identity Provider. When omitted, WorkOS generates + and manages the encryption key pair. + type: array + items: + $ref: '#/components/schemas/CreateConnectionKeyPairDto' + CreateConnectionOidcOptionsDto: + type: object + properties: + discovery_endpoint: + type: string + format: uri + description: The OIDC discovery endpoint. + example: https://idp.example.com/.well-known/openid-configuration + client_id: + type: string + description: The OIDC client ID. + example: client_123 + client_secret: + type: string + description: >- + The OIDC client secret. Required for `client_secret_basic` and + `client_secret_post`, and rejected for `private_key_jwt`, which + authenticates with a key pair instead. This value is write-only and + is never returned. + example: secret_xyz + redirect_uri: + type: string + format: uri + description: >- + A custom OAuth callback URL override. When omitted, the standard + WorkOS-generated redirect URI is used. + example: https://auth.workos.com/sso/oidc/conn_externalkey/callback + pkce: + type: boolean + description: Whether PKCE is enabled for the connection. + example: true + default: true + token_authentication_method: + type: string + enum: &ref_8 + - client_secret_post + - client_secret_basic + - private_key_jwt + description: The token-endpoint client authentication method. + example: client_secret_basic + default: client_secret_basic + jwt_signing_key_pair: + description: >- + A key pair for WorkOS to sign `private_key_jwt` client assertions + with. Only accepted when `token_authentication_method` is + `private_key_jwt`; when omitted, WorkOS generates one and returns + its certificate in `oidc_options.jwt_signing_certs`. + $ref: '#/components/schemas/CreateConnectionKeyPairDto' + id_token_signature_algorithm: + type: string + enum: &ref_9 + - ES256 + - ES384 + - ES512 + - EdDSA + - HS256 + - HS384 + - HS512 + - PS256 + - PS384 + - PS512 + - RS256 + - RS384 + - RS512 + description: The ID-token signing algorithm. + example: RS256 + fetch_user_info: + type: boolean + description: >- + Whether to fetch additional profile attributes from the userinfo + endpoint. + example: false + required: + - discovery_endpoint + - client_id + CreateConnectionStandardAttributesDto: + type: object + properties: + idp_id: + type: string + description: >- + The IdP attribute or claim the profile's `idp_id` is mapped from. + When omitted, the default for the connection type is used. + example: sub + email: + type: string + description: >- + The IdP attribute or claim the profile's `email` is mapped from. + When omitted, the default for the connection type is used. + example: email + first_name: + type: string + description: >- + The IdP attribute or claim the profile's `first_name` is mapped + from. When omitted, the default for the connection type is used. + example: given_name + last_name: + type: string + description: >- + The IdP attribute or claim the profile's `last_name` is mapped from. + When omitted, the default for the connection type is used. + example: family_name + groups: + type: + - string + - 'null' + description: >- + The IdP attribute or claim the profile's `groups` are mapped from. + `null` leaves the mapping unset. + example: memberOf + name: + type: + - string + - 'null' + description: >- + The IdP attribute or claim the profile's `name` is mapped from. + `null` leaves the mapping unset. + example: displayName + CreateConnectionAttributeMapsDto: + type: object + properties: + standard_attributes: + description: >- + How IdP attributes or claims map onto the standard WorkOS profile + fields. Provided fields override the defaults for the connection + type. + $ref: '#/components/schemas/CreateConnectionStandardAttributesDto' + custom_attributes: + type: object + description: >- + How IdP attributes or claims map onto custom attributes, keyed by + custom attribute name. Custom attributes must already be defined in + the WorkOS dashboard. + additionalProperties: + type: string + example: + company: company_claim + CreateConnectionDto: + allOf: + - type: object + properties: + organization_id: + type: string + description: >- + Unique identifier for the Organization in which the Connection + resides. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: >- + A human-readable name for the Connection. This will most + commonly be the organization's name. + example: Foo Corp + external_id: + type: string + maxLength: 128 + pattern: ^[\x00-\x7F]+$ + description: The customer-owned identifier for the Connection. + example: acme-legacy-conn-42 + connection_type: + type: string + description: >- + The type of the Connection. Only SAML and OIDC connection types + may be created. When omitted, the type is inferred from the + provided options. + example: OktaSAML + attribute_maps: + description: >- + How IdP attributes or claims map onto WorkOS profile fields. + Provided fields override the defaults for the connection type. + $ref: '#/components/schemas/CreateConnectionAttributeMapsDto' + required: + - organization_id + - oneOf: + - type: object + properties: + saml_options: + description: >- + Protocol configuration for SAML connections. Mutually + exclusive with `oidc_options`. + $ref: '#/components/schemas/CreateConnectionSamlOptionsDto' + required: + - saml_options + not: + anyOf: + - properties: + oidc_options: + x-exclude-from-lint: true + required: + - oidc_options + - type: object + properties: + oidc_options: + description: >- + Protocol configuration for OIDC connections. Mutually + exclusive with `saml_options`. + $ref: '#/components/schemas/CreateConnectionOidcOptionsDto' + required: + - oidc_options + not: + anyOf: + - properties: + saml_options: + x-exclude-from-lint: true + required: + - saml_options + x-mutually-exclusive-body-groups: *ref_7 + PatchConnectionSamlOptionsDto: + type: object + properties: + idp_metadata_url: + type: + - string + - 'null' + format: uri + description: >- + The Identity Provider metadata URL. When provided, the IdP fields + and signing certificates are re-imported from the metadata document, + replacing the current set. Mutually exclusive with the manual IdP + fields. Set to `null` to stop tracking a metadata URL. + example: https://idp.example.com/metadata.xml + acs_url: + type: + - string + - 'null' + format: uri + description: >- + A custom Assertion Consumer Service (ACS) URL override. Set to + `null` to revert to the standard WorkOS-generated ACS URL. + example: https://example.auth0.com/login/callback?connection=123 + sp_entity_id: + type: + - string + - 'null' + description: >- + A custom Service Provider Entity ID (audience) override. Set to + `null` to revert to the connection external key. + example: https://example.auth0.com/login/callback?connection=123 + idp_entity_id: + type: string + description: The Identity Provider Entity ID. + example: https://idp.example.com/entity + idp_sso_url: + type: string + format: uri + description: The Identity Provider SSO URL. + example: https://idp.example.com/sso + PatchConnectionOidcOptionsDto: + type: object + properties: + discovery_endpoint: + type: string + format: uri + description: The OIDC discovery endpoint. + example: https://idp.example.com/.well-known/openid-configuration + client_id: + type: string + description: The OIDC client ID. + example: client_123 + client_secret: + type: string + description: >- + The OIDC client secret. Required when moving the connection to + `client_secret_basic` or `client_secret_post`, and rejected for + `private_key_jwt`, which authenticates with a key pair instead. This + value is write-only and is never returned. + example: secret_xyz + redirect_uri: + type: + - string + - 'null' + format: uri + description: >- + A custom OAuth callback URL override. Set to `null` to revert to the + standard WorkOS-generated redirect URI. + example: https://auth.workos.com/sso/oidc/conn_externalkey/callback + pkce: + type: boolean + description: Whether PKCE is enabled for the connection. + example: true + token_authentication_method: + type: string + enum: *ref_8 + description: >- + The token-endpoint client authentication method. Moving to + `private_key_jwt` generates a signing key pair if the connection has + none; its certificate is returned in + `oidc_options.jwt_signing_certs` and must be registered at the + Identity Provider. + example: client_secret_basic + id_token_signature_algorithm: + type: string + enum: *ref_9 + description: The ID-token signing algorithm. + example: RS256 + fetch_user_info: + type: boolean + description: >- + Whether to fetch additional profile attributes from the userinfo + endpoint. + example: false + PatchConnectionStandardAttributesDto: + type: object + properties: + idp_id: + type: string + description: The IdP attribute or claim the profile's `idp_id` is mapped from. + example: sub + email: + type: string + description: The IdP attribute or claim the profile's `email` is mapped from. + example: email + first_name: + type: string + description: >- + The IdP attribute or claim the profile's `first_name` is mapped + from. + example: given_name + last_name: + type: string + description: The IdP attribute or claim the profile's `last_name` is mapped from. + example: family_name + groups: + type: + - string + - 'null' + description: >- + The IdP attribute or claim the profile's `groups` are mapped from. + Set to `null` to unset the mapping. + example: memberOf + name: + type: + - string + - 'null' + description: >- + The IdP attribute or claim the profile's `name` is mapped from. Set + to `null` to unset the mapping. + example: displayName + PatchConnectionAttributeMapsDto: + type: object + properties: + standard_attributes: + description: >- + How IdP attributes or claims map onto the standard WorkOS profile + fields. Only the provided fields are updated. + $ref: '#/components/schemas/PatchConnectionStandardAttributesDto' + custom_attributes: + type: object + description: >- + How IdP attributes or claims map onto custom attributes, keyed by + custom attribute name. Custom attributes must already be defined in + the WorkOS dashboard. Only the provided keys are updated; a `null` + value unsets that mapping. + additionalProperties: + oneOf: + - type: string + - type: 'null' + example: + company: company_claim + PatchConnectionDto: + allOf: + - type: object + properties: + name: + type: string + description: A human-readable name for the Connection. + example: Foo Corp + external_id: + type: + - string + - 'null' + maxLength: 128 + pattern: ^[\x00-\x7F]+$ + description: >- + The customer-owned identifier for the Connection. Set to `null` + to stop tracking one. + example: acme-legacy-conn-42 + connection_type: + type: string + description: >- + The type of the Connection. Immutable after creation — it may be + sent, but only with the Connection current type. + example: OktaSAML + attribute_maps: + description: >- + How IdP attributes or claims map onto WorkOS profile fields. + Only the provided fields are updated. + $ref: '#/components/schemas/PatchConnectionAttributeMapsDto' + - oneOf: + - type: object + not: + anyOf: + - properties: + saml_options: + x-exclude-from-lint: true + required: + - saml_options + - properties: + oidc_options: + x-exclude-from-lint: true + required: + - oidc_options + - type: object + properties: + saml_options: + description: >- + Protocol configuration for SAML connections. Only the + provided fields are updated. Mutually exclusive with + `oidc_options`. + $ref: '#/components/schemas/PatchConnectionSamlOptionsDto' + required: + - saml_options + not: + anyOf: + - properties: + oidc_options: + x-exclude-from-lint: true + required: + - oidc_options + - type: object + properties: + oidc_options: + description: >- + Protocol configuration for OIDC connections. Only the + provided fields are updated. Mutually exclusive with + `saml_options`. + $ref: '#/components/schemas/PatchConnectionOidcOptionsDto' + required: + - oidc_options + not: + anyOf: + - properties: + saml_options: + x-exclude-from-lint: true + required: + - saml_options + x-mutually-exclusive-body-groups: *ref_10 CreateCorsOriginDto: type: object properties: @@ -22331,11 +25724,11 @@ components: type: - object - 'null' - additionalProperties: &ref_7 + additionalProperties: &ref_11 type: string maxLength: 600 maxProperties: 50 - example: &ref_8 + example: &ref_12 tier: diamond description: >- Object containing [metadata](/authkit/metadata) key/value pairs @@ -22390,9 +25783,9 @@ components: type: - object - 'null' - additionalProperties: *ref_7 + additionalProperties: *ref_11 maxProperties: 50 - example: *ref_8 + example: *ref_12 description: >- Object containing [metadata](/authkit/metadata) key/value pairs associated with the Organization. @@ -22526,7 +25919,7 @@ components: example: application/x-www-form-urlencoded authenticate_via: type: string - enum: &ref_9 + enum: &ref_13 - request_body - basic_auth_header description: >- @@ -22682,7 +26075,7 @@ components: example: application/x-www-form-urlencoded authenticate_via: type: string - enum: *ref_9 + enum: *ref_13 description: >- How client credentials are sent when exchanging authorization codes and refreshing tokens. @@ -22858,6 +26251,15 @@ components: example: https://example.com/callback required: - uri + CreateSamlIdpSigningCertificateDto: + type: object + properties: + value: + type: string + description: The PEM-encoded X.509 certificate. + example: '-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----' + required: + - value CreateTeamDto: type: object properties: @@ -23238,9 +26640,9 @@ components: x-exclude-from-lint: true required: - role_slug - x-mutually-exclusive-body-groups: *ref_10 + x-mutually-exclusive-body-groups: *ref_14 UpdateUserlandUserOrganizationMembershipDto: - x-mutually-exclusive-body-groups: *ref_11 + x-mutually-exclusive-body-groups: *ref_15 oneOf: - type: object not: @@ -23362,9 +26764,9 @@ components: type: - object - 'null' - additionalProperties: *ref_7 + additionalProperties: *ref_11 maxProperties: 50 - example: &ref_13 + example: &ref_17 timezone: America/New_York description: >- Object containing metadata key/value pairs associated with the @@ -23463,7 +26865,7 @@ components: example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy password_hash_type: type: string - enum: &ref_14 + enum: &ref_18 - bcrypt - firebase-scrypt - ssha @@ -23478,7 +26880,7 @@ components: example: bcrypt password_salt_position: type: string - enum: &ref_15 + enum: &ref_19 - prefix - suffix description: >- @@ -23499,7 +26901,7 @@ components: x-exclude-from-lint: true required: - password - x-mutually-exclusive-body-groups: *ref_12 + x-mutually-exclusive-body-groups: *ref_16 UpdateUserlandUserDto: allOf: - type: object @@ -23529,9 +26931,9 @@ components: type: - object - 'null' - additionalProperties: *ref_7 + additionalProperties: *ref_11 maxProperties: 50 - example: *ref_13 + example: *ref_17 description: >- Object containing metadata key/value pairs associated with the user. @@ -23613,7 +27015,7 @@ components: example: $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy password_hash_type: type: string - enum: *ref_14 + enum: *ref_18 description: >- The algorithm originally used to hash the password, used when providing a `password_hash`. Required with @@ -23621,7 +27023,7 @@ components: example: bcrypt password_salt_position: type: string - enum: *ref_15 + enum: *ref_19 description: >- The position of the salt relative to the password when the `password_hash` digest was computed: `prefix` for `hash(salt @@ -23640,7 +27042,7 @@ components: x-exclude-from-lint: true required: - password - x-mutually-exclusive-body-groups: *ref_16 + x-mutually-exclusive-body-groups: *ref_20 VerifyEmailAddressDto: type: object properties: @@ -23715,8 +27117,9 @@ components: type: object description: >- Object containing additional key/value pairs collected with the - waitlist entry. Values are user-provided — treat them as untrusted - input when rendering or exporting. + waitlist entry. Supports up to 50 string pairs, with keys up to 40 + characters and values up to 600 characters. Values are user-provided + — treat them as untrusted input when rendering or exporting. additionalProperties: type: string maxLength: 600 @@ -23746,10 +27149,14 @@ components: description: The events that the Webhook Endpoint is subscribed to. items: type: string - enum: &ref_17 + enum: &ref_21 - agent.blueprint.created - agent.blueprint.deleted - agent.blueprint.updated + - agent.instance.created + - agent.instance.deleted + - agent.instance.session.created + - agent.instance.session.revoked - agent.registration.created - agent.registration.claim.attempt.created - agent.registration.claim.completed @@ -23868,7 +27275,7 @@ components: description: The events that the Webhook Endpoint is subscribed to. items: type: string - enum: *ref_17 + enum: *ref_21 example: - user.created - dsync.user.created @@ -24559,6 +27966,268 @@ components: - status - user_code - organizations + AgentBlueprint: + type: object + properties: + object: + type: string + description: Distinguishes the agent blueprint object. + const: agent_blueprint + id: + type: string + description: Unique identifier of the agent blueprint. + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: Human-readable name of the agent blueprint. + example: Prospecting Agent + description: + type: + - string + - 'null' + description: Human-readable description of the agent blueprint. + example: Finds and qualifies sales prospects. + permissions: + type: array + items: + type: string + description: >- + Permission slugs forming the ceiling on what sessions minted from + this blueprint may do. + example: + - crm:read + - email:send + invocable_by: + type: object + properties: + role_slugs: + type: array + items: + type: string + description: >- + Role slugs whose members may mint user-delegated sessions from + this blueprint. + example: + - manager + organization_ids: + type: array + items: + type: string + description: >- + Organizations in which sessions may be minted from this + blueprint, enforced on user-delegated, autonomous, and + agent-delegated mints. + example: + - org_01EHWNCE74X7JSDV0X3SZ3KJNY + required: + - role_slugs + - organization_ids + description: Who may mint sessions from this blueprint. + session_settings: + type: object + properties: + max_age_seconds: + type: integer + description: >- + Maximum lifetime of a session in seconds; refreshes never extend + a session past this. + example: 3600 + access_token_ttl_seconds: + type: integer + description: Lifetime of each minted access token in seconds. + example: 300 + refresh_token_ttl_seconds: + type: integer + description: Lifetime of each rotated refresh token in seconds. + example: 3600 + required: + - max_age_seconds + - access_token_ttl_seconds + - refresh_token_ttl_seconds + description: Token and session lifetimes for sessions minted from this blueprint. + created_at: + type: string + format: date-time + description: Timestamp when the agent blueprint was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + format: date-time + description: Timestamp when the agent blueprint was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - name + - description + - permissions + - invocable_by + - session_settings + - created_at + - updated_at + AgentInstance: + type: object + properties: + object: + type: string + description: Distinguishes the agent instance object. + const: agent_instance + id: + type: string + description: Unique identifier of the agent instance. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + agent_blueprint_id: + type: string + description: The blueprint this instance was minted from. + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The organization the instance acts within. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_membership_id: + type: + - string + - 'null' + description: >- + The organization membership of the delegating user; `null` for + autonomous instances. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + enum: + - delegated + - autonomous + description: >- + Whether the instance acts on behalf of a specific user (`delegated`) + or as itself (`autonomous`). + created_at: + type: string + format: date-time + description: Timestamp when the agent instance was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + format: date-time + description: Timestamp when the agent instance was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - agent_blueprint_id + - organization_id + - organization_membership_id + - type + - created_at + - updated_at + AgentToken: + type: object + properties: + access_token: + type: string + description: The agent access token (a JWT) carrying the effective permissions. + example: eyJhbGciOiJSUzI1NiIsImtpZCI6... + token_type: + type: string + description: Always `Bearer`. + const: Bearer + expires_in: + type: integer + description: Number of seconds until the access token expires. + example: 300 + refresh_token: + type: string + description: >- + Single-use refresh token for rotating the access token within the + session lifetime. + example: njGkA8Wyht0GBEGGA0Zh1Q3wZzL2... + agent_instance_id: + type: string + description: The agent instance the session belongs to. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + new_instance: + type: boolean + description: >- + Whether this mint created the agent instance: `true` only for the + mint that inserted the row, `false` when an existing instance was + reused (including when a concurrent mint inserted it first). + example: false + agent_instance_session_id: + type: string + description: The backing agent instance session. + example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY + permissions: + type: array + items: + type: string + description: The effective permission slugs carried by the token. + example: + - crm:read + required: + - access_token + - token_type + - expires_in + - refresh_token + - agent_instance_id + - new_instance + - agent_instance_session_id + - permissions + AgentInstanceSession: + type: object + properties: + object: + type: string + description: Distinguishes the agent instance session object. + const: agent_instance_session + id: + type: string + description: Unique identifier of the agent instance session. + example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY + agent_instance_id: + type: string + description: The agent instance the session belongs to. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + status: + type: string + enum: + - active + - revoked + - expired + description: >- + Derived from `revoked_at` and `expires_at` at read time; a revoked + session stays `revoked` even after it expires. + expires_at: + type: string + format: date-time + description: Timestamp when the session expires. + example: '2026-01-15T13:00:00.000Z' + revoked_at: + type: + - string + - 'null' + format: date-time + description: >- + Timestamp when the session was revoked; `null` if it has not been + revoked. + example: null + created_at: + type: string + format: date-time + description: Timestamp when the session was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + format: date-time + description: Timestamp when the session was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - agent_instance_id + - status + - expires_at + - revoked_at + - created_at + - updated_at ApiKey: type: object properties: @@ -27194,7 +30863,7 @@ components: description: >- An object containing the custom attribute mapping for the Directory Provider. - example: &ref_23 + example: &ref_27 department: Engineering job_title: Software Engineer role: @@ -27388,7 +31057,7 @@ components: type: object additionalProperties: {} description: The event payload. - example: &ref_18 + example: &ref_22 id: directory_user_01E1JG7J09H96KYP8HM9B0G5SJ directory_id: directory_01ECAZ4NV9QMV47GW873HDCX74 organization_id: org_01EZTR6WYX1A0DSE2CYMGXQ24Y @@ -27423,11 +31092,11 @@ components: - data - created_at description: An event emitted by WorkOS. - example: &ref_28 + example: &ref_32 object: event id: event_01EHZNVPK3SFK441A1RGBFSHRT event: dsync.user.created - data: *ref_18 + data: *ref_22 created_at: '2021-06-25T19:07:33.155Z' context: {} - oneOf: @@ -27627,7 +31296,7 @@ components: description: >- Permission slugs forming the ceiling on what sessions minted from this blueprint may do. - example: &ref_19 + example: &ref_23 - crm:read - email:send invocable_by: @@ -27640,7 +31309,7 @@ components: description: >- Role slugs whose members may mint user-delegated sessions from this blueprint. - example: &ref_20 + example: &ref_24 - manager organization_ids: type: array @@ -27649,7 +31318,7 @@ components: description: >- Organizations in which autonomous sessions may be minted from this blueprint. - example: &ref_21 + example: &ref_25 - org_01EHWNCE74X7JSDV0X3SZ3KJNY required: - role_slugs @@ -27779,99 +31448,417 @@ components: example: event_01EHZNVPK3SFK441A1RGBFSHRT event: type: string - const: agent.blueprint.updated + const: agent.blueprint.updated + data: + type: object + properties: + object: + type: string + description: Distinguishes the agent blueprint object. + const: agent_blueprint + id: + type: string + description: Unique identifier of the agent blueprint. + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + name: + type: string + description: Human-readable name of the agent blueprint. + example: Prospecting Agent + description: + type: + - string + - 'null' + description: Human-readable description of the agent blueprint. + example: Finds and qualifies sales prospects. + permissions: + type: array + items: + type: string + description: >- + Permission slugs forming the ceiling on what sessions + minted from this blueprint may do. + example: *ref_23 + invocable_by: + type: object + properties: + role_slugs: + type: array + items: + type: string + description: >- + Role slugs whose members may mint user-delegated + sessions from this blueprint. + example: *ref_24 + organization_ids: + type: array + items: + type: string + description: >- + Organizations in which autonomous sessions may be + minted from this blueprint. + example: *ref_25 + required: + - role_slugs + - organization_ids + description: Who may mint sessions from this blueprint. + session_settings: + type: object + properties: + max_age_seconds: + type: number + description: >- + Maximum lifetime of a session in seconds; refreshes + never extend a session past this. + example: 3600 + access_token_ttl_seconds: + type: number + description: Lifetime of each minted access token in seconds. + example: 300 + refresh_token_ttl_seconds: + type: number + description: Lifetime of each rotated refresh token in seconds. + example: 3600 + required: + - max_age_seconds + - access_token_ttl_seconds + - refresh_token_ttl_seconds + description: >- + Token and session lifetimes for sessions minted from + this blueprint. + created_at: + type: string + description: The timestamp when the agent blueprint was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the agent blueprint was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - name + - description + - permissions + - invocable_by + - session_settings + - 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: agent.instance.created + data: + type: object + properties: + object: + type: string + description: Distinguishes the agent instance object. + const: agent_instance + id: + type: string + description: Unique identifier of the agent instance. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + agent_blueprint_id: + type: string + description: The agent blueprint this instance was minted from. + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The organization the instance acts within. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_membership_id: + type: + - string + - 'null' + description: >- + The organization membership the instance acts on behalf + of; `null` for an autonomous instance. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + enum: + - delegated + - autonomous + description: >- + Whether the instance acts on behalf of a user + (`delegated`) or as itself within an organization + (`autonomous`). + created_at: + type: string + description: The timestamp when the agent instance was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the agent instance was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - agent_blueprint_id + - organization_id + - organization_membership_id + - 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: agent.instance.deleted + data: + type: object + properties: + object: + type: string + description: Distinguishes the agent instance object. + const: agent_instance + id: + type: string + description: Unique identifier of the agent instance. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + agent_blueprint_id: + type: string + description: The agent blueprint this instance was minted from. + example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The organization the instance acts within. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_membership_id: + type: + - string + - 'null' + description: >- + The organization membership the instance acts on behalf + of; `null` for an autonomous instance. + example: om_01EHWNCE74X7JSDV0X3SZ3KJNY + type: + type: string + enum: + - delegated + - autonomous + description: >- + Whether the instance acts on behalf of a user + (`delegated`) or as itself within an organization + (`autonomous`). + created_at: + type: string + description: The timestamp when the agent instance was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the agent instance was last updated. + example: '2026-01-15T12:00:00.000Z' + required: + - object + - id + - agent_blueprint_id + - organization_id + - organization_membership_id + - 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: agent.instance.session.created data: type: object properties: object: type: string - description: Distinguishes the agent blueprint object. - const: agent_blueprint + description: Distinguishes the agent instance session object. + const: agent_instance_session id: type: string - description: Unique identifier of the agent blueprint. - example: agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY - name: + description: Unique identifier of the agent instance session. + example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY + agent_instance_id: type: string - description: Human-readable name of the agent blueprint. - example: Prospecting Agent - description: + description: The agent instance the session belongs to. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The organization the owning agent instance belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + expires_at: + type: string + description: Timestamp when the session expires. + example: '2026-01-15T13:00:00.000Z' + revoked_at: type: - string - 'null' - description: Human-readable description of the agent blueprint. - example: Finds and qualifies sales prospects. - permissions: + description: >- + Timestamp when the session was revoked; `null` if it has + not been revoked. + example: null + created_at: + type: string + description: The timestamp when the session was created. + example: '2026-01-15T12:00:00.000Z' + updated_at: + type: string + description: The timestamp when the session was last updated. + example: '2026-01-15T12:00:00.000Z' + permission_slugs: type: array items: type: string + description: The permissions granted to the session at mint time. + example: + - crm:read + required: + - object + - id + - agent_instance_id + - organization_id + - expires_at + - revoked_at + - created_at + - updated_at + - permission_slugs + 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: agent.instance.session.revoked + data: + type: object + properties: + object: + type: string + description: Distinguishes the agent instance session object. + const: agent_instance_session + id: + type: string + description: Unique identifier of the agent instance session. + example: agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY + agent_instance_id: + type: string + description: The agent instance the session belongs to. + example: agent_01EHWNCE74X7JSDV0X3SZ3KJNY + organization_id: + type: string + description: The organization the owning agent instance belongs to. + example: org_01EHWNCE74X7JSDV0X3SZ3KJNY + expires_at: + type: string + description: Timestamp when the session expires. + example: '2026-01-15T13:00:00.000Z' + revoked_at: + type: + - string + - 'null' description: >- - Permission slugs forming the ceiling on what sessions - minted from this blueprint may do. - example: *ref_19 - invocable_by: - type: object - properties: - role_slugs: - type: array - items: - type: string - description: >- - Role slugs whose members may mint user-delegated - sessions from this blueprint. - example: *ref_20 - organization_ids: - type: array - items: - type: string - description: >- - Organizations in which autonomous sessions may be - minted from this blueprint. - example: *ref_21 - required: - - role_slugs - - organization_ids - description: Who may mint sessions from this blueprint. - session_settings: - type: object - properties: - max_age_seconds: - type: number - description: >- - Maximum lifetime of a session in seconds; refreshes - never extend a session past this. - example: 3600 - access_token_ttl_seconds: - type: number - description: Lifetime of each minted access token in seconds. - example: 300 - refresh_token_ttl_seconds: - type: number - description: Lifetime of each rotated refresh token in seconds. - example: 3600 - required: - - max_age_seconds - - access_token_ttl_seconds - - refresh_token_ttl_seconds - description: >- - Token and session lifetimes for sessions minted from - this blueprint. + Timestamp when the session was revoked; `null` if it has + not been revoked. + example: null created_at: type: string - description: The timestamp when the agent blueprint was created. + description: The timestamp when the session was created. example: '2026-01-15T12:00:00.000Z' updated_at: type: string - description: The timestamp when the agent blueprint was last updated. + description: The timestamp when the session was last updated. example: '2026-01-15T12:00:00.000Z' required: - object - id - - name - - description - - permissions - - invocable_by - - session_settings + - agent_instance_id + - organization_id + - expires_at + - revoked_at - created_at - updated_at description: The event payload. @@ -28545,7 +32532,7 @@ components: items: type: string description: The permissions granted to the API key. - example: &ref_22 + example: &ref_26 - users:read - users:write created_at: @@ -28671,7 +32658,7 @@ components: items: type: string description: The permissions granted to the API key. - example: *ref_22 + example: *ref_26 created_at: type: string description: The timestamp when the API key was created. @@ -28795,7 +32782,7 @@ components: items: type: string description: The permissions granted to the API key. - example: *ref_22 + example: *ref_26 created_at: type: string description: The timestamp when the API key was created. @@ -31662,7 +35649,7 @@ components: description: >- An object containing the custom attribute mapping for the Directory Provider. - example: *ref_23 + example: *ref_27 role: $ref: '#/components/schemas/SlimRole' roles: @@ -31852,7 +35839,7 @@ components: description: >- Labels assigned to the Feature Flag for categorizing and filtering. - example: &ref_24 + example: &ref_28 - reports enabled: type: boolean @@ -32013,7 +36000,7 @@ components: description: >- Labels assigned to the Feature Flag for categorizing and filtering. - example: *ref_24 + example: *ref_28 enabled: type: boolean description: >- @@ -32173,7 +36160,7 @@ components: description: >- Labels assigned to the Feature Flag for categorizing and filtering. - example: *ref_24 + example: *ref_28 enabled: type: boolean description: >- @@ -32453,7 +36440,7 @@ components: description: >- Labels assigned to the Feature Flag for categorizing and filtering. - example: *ref_24 + example: *ref_28 enabled: type: boolean description: >- @@ -33441,7 +37428,7 @@ components: description: >- Object containing [metadata](/authkit/metadata) key/value pairs associated with the Organization. - example: &ref_25 + example: &ref_29 tier: diamond propertyNames: maxLength: 40 @@ -33591,7 +37578,7 @@ components: description: >- Object containing [metadata](/authkit/metadata) key/value pairs associated with the Organization. - example: *ref_25 + example: *ref_29 propertyNames: maxLength: 40 maxProperties: 50 @@ -34418,7 +38405,7 @@ components: items: type: string description: The permissions granted by the role. - example: &ref_26 + example: &ref_30 - users:read - users:write created_at: @@ -34502,7 +38489,7 @@ components: items: type: string description: The permissions granted by the role. - example: *ref_26 + example: *ref_30 created_at: format: date-time type: string @@ -34584,7 +38571,7 @@ components: items: type: string description: The permissions granted by the role. - example: *ref_26 + example: *ref_30 created_at: format: date-time type: string @@ -34721,7 +38708,7 @@ components: description: >- Object containing [metadata](/authkit/metadata) key/value pairs associated with the Organization. - example: *ref_25 + example: *ref_29 propertyNames: maxLength: 40 maxProperties: 50 @@ -35398,6 +39385,7 @@ components: - organizations - events - sessions + - auditLogEvents description: The type of resource being exported. example: users required: @@ -35444,6 +39432,7 @@ components: - organizations - events - sessions + - auditLogEvents description: The type of resource being exported. example: users required: @@ -35490,6 +39479,7 @@ components: - organizations - events - sessions + - auditLogEvents description: The type of resource being exported. example: users required: @@ -35536,6 +39526,7 @@ components: - organizations - events - sessions + - auditLogEvents description: The type of resource being exported. example: users required: @@ -35588,7 +39579,7 @@ components: items: type: string description: The permissions granted by the role. - example: &ref_27 + example: &ref_31 - users:read - users:write created_at: @@ -35654,7 +39645,7 @@ components: items: type: string description: The permissions granted by the role. - example: *ref_27 + example: *ref_31 created_at: format: date-time type: string @@ -35718,7 +39709,7 @@ components: items: type: string description: The permissions granted by the role. - example: *ref_27 + example: *ref_31 created_at: format: date-time type: string @@ -36858,7 +40849,7 @@ components: - data - created_at - object - example: *ref_28 + example: *ref_32 description: An event emitted by WorkOS. EventList: type: object @@ -36893,7 +40884,7 @@ components: example: object: list data: - - *ref_28 + - *ref_32 list_metadata: after: event_01EHZNVPK3SFK441A1RGBFSHRT JwtTemplate: @@ -39022,6 +43013,169 @@ components: - default - created_at - updated_at + SamlIdpSigningCertificate: + type: object + properties: + object: + type: string + description: Distinguishes the SAML Identity Provider signing certificate object. + const: saml_idp_signing_certificate + id: + type: string + description: Unique identifier for the Identity Provider signing certificate. + example: saml_x509_cert_01E4ZCR3C56J083X43JQXF3JK5 + value: + type: string + description: The PEM-encoded public X.509 certificate. + example: '-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----' + not_before: + format: date-time + type: + - string + - 'null' + description: When the certificate becomes valid. + example: '2026-01-15T12:00:00.000Z' + not_after: + format: date-time + type: + - string + - 'null' + description: When the certificate 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' + required: + - object + - id + - value + - not_before + - not_after + - created_at + SamlIdpSigningCertificateList: + type: object + properties: + object: + type: string + example: list + const: list + data: + type: array + items: + $ref: '#/components/schemas/SamlIdpSigningCertificate' + description: >- + Every Identity Provider signing certificate on the Connection, + including expired ones, oldest first. + required: + - object + - data + SamlSpEncryptionCertificate: + type: object + properties: + object: + type: string + description: >- + Distinguishes the SAML Service Provider encryption certificate + object. + const: saml_sp_encryption_certificate + id: + type: string + description: >- + Unique identifier for the Service Provider encryption key pair. + WorkOS holds the corresponding private key, which is never exposed. + example: saml_enc_key_pair_01E4ZCR3C56J083X43JQXF3JK5 + value: + type: string + description: The PEM-encoded public X.509 certificate. + example: '-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----' + not_before: + format: date-time + type: + - string + - 'null' + description: When the certificate becomes valid. + example: '2026-01-15T12:00:00.000Z' + not_after: + format: date-time + type: + - string + - 'null' + description: When the certificate 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' + required: + - object + - id + - value + - not_before + - not_after + - created_at + SamlSpEncryptionCertificateList: + type: object + properties: + object: + type: string + example: list + const: list + data: + type: array + items: + $ref: '#/components/schemas/SamlSpEncryptionCertificate' + description: >- + Every Service Provider encryption certificate on the Connection, + including expired ones. + required: + - object + - data + SamlSpSigningCertificate: + type: object + properties: + object: + type: string + description: Distinguishes the SAML Service Provider signing certificate object. + const: saml_sp_signing_certificate + id: + type: string + description: >- + Unique identifier for the Service Provider signing key pair. WorkOS + holds the corresponding private key, which is never exposed. + example: saml_party_trust_01E4ZCR3C56J083X43JQXF3JK5 + value: + type: string + description: The PEM-encoded public X.509 certificate. + example: '-----BEGIN CERTIFICATE-----MIIC...-----END CERTIFICATE-----' + not_before: + format: date-time + type: + - string + - 'null' + description: When the certificate becomes valid. + example: '2026-01-15T12:00:00.000Z' + not_after: + format: date-time + type: + - string + - 'null' + description: When the certificate 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' + required: + - object + - id + - value + - not_before + - not_after + - created_at Team: type: object properties: