openapi: 3.0.0 info: service: common tags: - name: External Sync Tokens description: >- Manage the tokens an identity provider uses to provision users and groups into a zone over SCIM x-displayName: External Sync Tokens - name: Zones x-displayName: Zones - name: Applications x-displayName: Applications - name: Application Credentials x-displayName: Application Credentials - name: Delegated Grants x-displayName: Delegated Grants - name: Providers x-displayName: Providers - name: Resources x-displayName: Resources - name: Zone Roles x-displayName: Zone Roles - name: Groups x-displayName: Groups - name: Sessions x-displayName: Sessions - name: User Agents x-displayName: User Agents - name: Users x-displayName: Users - name: Organizations - name: Organization Invitations - name: Service Accounts - name: Service Account Credentials - name: SSO Connection - name: PolicySchemas description: > Zone-scoped Cedar schema management. The Cedar schema defines the entity model used for authorization decisions. Key entity types and their attributes: - **Keycard::User** — `email` (String), `groups` (Set of String) - **Keycard::Application** — `registration_method` (RegistrationMethod entity), `credential_type` (CredentialType entity) - **Keycard::RegistrationMethod** — enum entity: `"managed"`, `"dcr"` - **Keycard::CredentialType** — enum entity: `"token"`, `"password"`, `"public-key"`, `"url"`, `"public"` - **Keycard::Resource** — `id` (String), `name` (String), `scopes` (Set of String) - **Keycard::Claims** — `email` (String), `groups` (Set of String), `issuer_claims` (issuer-specific claims record), plus arbitrary additional fields Enum-like attributes use Cedar enum entity types (schema version `2026-03-16`+). In policies, reference values as `RegistrationMethod::"managed"` or `CredentialType::"token"`. See the Credentials API spec for the full entity model reference. x-displayName: PolicySchemas - name: Policies description: Policy CRUD operations x-displayName: Policies - name: PolicyVersions description: Immutable policy version snapshots x-displayName: PolicyVersions - name: PolicyDrafts description: Mutable policy authoring workspace x-displayName: PolicyDrafts - name: PolicySets description: Policy set CRUD and binding management x-displayName: PolicySets - name: PolicySetVersions description: Immutable policy set manifest snapshots x-displayName: PolicySetVersions - name: PolicySetDrafts description: Mutable policy set manifest workspace x-displayName: PolicySetDrafts - name: PolicySetManifest description: Declarative read/apply of a policy set's full content x-displayName: PolicySetManifest - name: PolicyEvaluations description: Stateless policy evaluation testing x-displayName: PolicyEvaluations - name: PolicyValidations description: Stateless Cedar policy validation x-displayName: PolicyValidations - name: PolicyBindings description: | Policy set binding management. Active slots are replace-only by design: once bound (at zone bootstrap or on a principal's first policy check), an active slot is never emptied — evaluation fails closed, so an empty active slot would deny all access. Replace the bound version rather than removing the binding. DELETE applies to shadow bindings only. x-displayName: PolicyBindings - name: Secrets paths: /zones: servers: [] post: operationId: createZone summary: Create zone tags: - Zones description: >- Creates a new zone for the authenticated organization. A zone is an isolated environment for IAM resources. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ZoneCreate' security: - bearerAuth: [] - OAuth2: [] responses: '200': description: A zone for organizing resources within an organization content: application/json: schema: $ref: '#/components/schemas/iam_Zone' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' get: operationId: listZones summary: List zones tags: - Zones description: >- Returns a list of zones for the authenticated organization. Cursor pagination via `after`/`before` and `limit`, plus `expand[]=total_count`, name substring search, and `sort`, are supported on every request. `filter[permission][in]` narrows the list to zones where the caller holds at least one of the given permissions. parameters: - schema: type: string in: query name: slug required: false - schema: type: string in: query name: cursor required: false - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - permissions - type: array items: type: string enum: - total_count - permissions in: query name: expand[] required: false - schema: type: string in: query name: filter[organization_id] required: false - schema: anyOf: - type: string - maxItems: 20 type: array items: type: string in: query name: filter[permission][in] required: false description: >- Only return zones where the caller is allowed ANY of these permissions (`:`, e.g. `applications:list`). Repeatable (one permission per occurrence); values are unioned, max 20 (a stricter cap than the authorization service's 50). The accessible zone set is resolved by the authorization service and composes with cursor pagination, search, sort and `expand[]=total_count`. Malformed values are a 400. security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - page_info - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Zone' page_info: allOf: - $ref: '#/components/schemas/iam_PageInfo' deprecated: true description: >- Deprecated: read cursor state from `pagination` instead. This field is retained for backward compatibility and will be removed in a future version. pagination: $ref: '#/components/schemas/iam_Pagination' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}: servers: [] get: operationId: getZone summary: Get zone tags: - Zones description: Returns details of a specific zone by ID parameters: - schema: anyOf: - type: string enum: - permissions - type: array items: type: string enum: - permissions in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: A zone for organizing resources within an organization content: application/json: schema: $ref: '#/components/schemas/iam_Zone' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateZone summary: Update zone tags: - Zones description: Updates a zone's configuration (partial update) requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ZoneUpdate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: A zone for organizing resources within an organization content: application/json: schema: $ref: '#/components/schemas/iam_Zone' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteZone summary: Delete zone tags: - Zones description: Permanently deletes a zone and all its associated resources parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications: servers: [] get: operationId: listApplications summary: List applications tags: - Applications description: >- Returns a paginated list of applications in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending. Use `expand[]=total_count` to include the matching row count. Filter by exact slug via `filter[slug]` and by exact identifier via `filter[identifier]`. Search via `query[name]` / `query[identifier]` / `query[]` (substring match, OR'd across repeated values). `query[]` matches against name and identifier. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of applications — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested application that exists in the zone, in a single page. IDs not in the zone are silently omitted. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: anyOf: - description: Filter by exact application slug type: string - maxItems: 100 type: array items: type: string in: query name: filter[slug] required: false - schema: anyOf: - description: Filter by exact application identifier type: string - maxItems: 100 type: array items: type: string in: query name: filter[identifier] required: false - schema: anyOf: - description: >- Restrict results to applications with this publicId. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: type: string enum: - platform - customer in: query name: filter[owner_type] required: false description: >- Filter by owner type: `platform` (Keycard-managed) or `customer` (org-created). - schema: type: string enum: - platform - customer in: query name: filter[owner_type][ne] required: false description: >- Exclude applications with this owner type, e.g. `filter[owner_type][ne]=platform` returns only org-created applications. - schema: type: string in: query name: slug required: false - schema: type: string in: query name: identifier required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by name (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[name] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[identifier] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search across name and identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: pattern: ^-?(created_at|name|identifier)(,\s*-?(created_at|name|identifier))*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, name, identifier - schema: type: string in: path name: zoneId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - page_info - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Application' page_info: allOf: - $ref: '#/components/schemas/iam_PageInfo' deprecated: true description: >- Deprecated: read cursor state from `pagination` instead. This field is retained for backward compatibility and will be removed in a future version. pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createApplication summary: Create application tags: - Applications description: >- Creates a new Application - a software system with an identity that can access Resources requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationCreate' parameters: - schema: type: string in: path name: zoneId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- An Application is a software system with an associated identity that can access Resources. It may act on its own behalf (machine-to-machine) or on behalf of a user (delegated access). content: application/json: schema: $ref: '#/components/schemas/iam_Application' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{id}: servers: [] get: operationId: getApplication summary: Get application tags: - Applications description: Returns details of a specific Application by ID parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- An Application is a software system with an associated identity that can access Resources. It may act on its own behalf (machine-to-machine) or on behalf of a user (delegated access). content: application/json: schema: $ref: '#/components/schemas/iam_Application' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateApplication summary: Update application tags: - Applications description: Updates an Application's configuration and metadata requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationUpdate' parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- An Application is a software system with an associated identity that can access Resources. It may act on its own behalf (machine-to-machine) or on behalf of a user (delegated access). content: application/json: schema: $ref: '#/components/schemas/iam_Application' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteApplication summary: Delete application tags: - Applications description: Permanently deletes an application parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{id}/dependencies: servers: [] get: operationId: listApplicationDependencies summary: List application dependencies tags: - Applications description: Returns resource dependencies for an application parameters: - schema: type: string in: query name: when_accessing required: false - schema: type: string in: query name: cursor required: false - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Resource' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{id}/dependencies/{dependencyId}: servers: [] put: operationId: addApplicationDependency summary: Add application dependency tags: - Applications description: Adds a resource dependency to an application parameters: - schema: type: array items: type: string in: query name: when_accessing required: false - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true - schema: type: string in: path name: dependencyId required: true security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: removeApplicationDependency summary: Remove application dependency tags: - Applications description: Removes a resource dependency from an application parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true - schema: type: string in: path name: dependencyId required: true security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' get: operationId: getApplicationDependency summary: Get application dependency tags: - Applications description: Retrieves a specific resource dependency of an application parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true - schema: type: string in: path name: dependencyId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Resource is a system that exposes protected information or functionality. It requires authentication of the requesting actor, which may be a user or application, before allowing access. content: application/json: schema: $ref: '#/components/schemas/iam_Resource' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{id}/application-credentials: servers: [] get: operationId: listApplicationCredentialsForApplication summary: List application credentials tags: - Applications description: Returns a list of application credentials for a specific application parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - page_info - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_ApplicationCredential' page_info: $ref: '#/components/schemas/iam_PageInfo' pagination: $ref: '#/components/schemas/iam_Pagination' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{id}/resources: servers: [] get: operationId: listApplicationResources summary: List application resources tags: - Applications description: Returns a list of resources provided by an application parameters: - schema: type: string in: query name: cursor required: false - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Resource' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/application-credentials: servers: [] get: operationId: listApplicationCredentials summary: List application credentials tags: - Application Credentials description: >- Returns a paginated list of application credentials in the specified zone. Use cursor pagination via `after`/`before`. Use `expand[]=total_count` to include the matching row count. Search via `query[identifier]`, `query[provider_name]`, or `query[]` (identifier or provider name); all are substring matches, OR'd across repeated values. parameters: - schema: type: string in: query name: slug required: false - schema: type: string in: query name: applicationId required: false - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string enum: - platform - customer in: query name: filter[owner_type][ne] required: false description: >- Exclude credentials whose owning application has this owner type, e.g. `filter[owner_type][ne]=platform` returns only credentials of org-created applications. - schema: anyOf: - type: string - maxItems: 100 type: array items: type: string in: query name: filter[traits][ne] required: false description: >- Exclude credentials whose owning application has this trait. A single value excludes that trait; repeated params accumulate into a not-in set (max 100), so a credential matches when its application's traits contain none of them. Each value is a single literal trait; a comma is a literal character in the value, not a delimiter. - schema: anyOf: - type: string enum: - token - password - public-key - url - public description: >- Filter by credential type; repeated values are OR'd, e.g. `filter[type]=token&filter[type]=password`. - maxItems: 100 type: array items: type: string enum: - token - password - public-key - url - public in: query name: filter[type] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: >- Search by credential identifier (substring match, OR'd across repeated values) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[identifier] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: >- Search by the linked provider's name (substring match, OR'd across repeated values) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[provider_name] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: >- Search across credential identifier and linked provider name (substring match, OR'd across repeated values) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: pattern: ^-?created_at(,\s*-?created_at)*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at - schema: type: string in: path name: zoneId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - page_info - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_ApplicationCredential' page_info: allOf: - $ref: '#/components/schemas/iam_PageInfo' deprecated: true description: >- Deprecated: read cursor state from `pagination` instead. This field is retained for backward compatibility and will be removed in a future version. pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createApplicationCredential summary: Create application credential tags: - Application Credentials description: Creates a new application credential requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationCredentialCreate' parameters: - schema: type: string in: path name: zoneId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Response for creating a new application credential content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationCredentialCreateResponse' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/application-credentials/{id}: servers: [] get: operationId: getApplicationCredential summary: Get application credential tags: - Application Credentials description: Returns details of a specific application credential by ID parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Credentials for accessing external services from applications content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationCredential' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateApplicationCredential summary: Update application credential tags: - Application Credentials description: Updates an application credential's configuration requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationCredentialUpdate' parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Credentials for accessing external services from applications content: application/json: schema: $ref: '#/components/schemas/iam_ApplicationCredential' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteApplicationCredential summary: Delete application credential tags: - Application Credentials description: Permanently deletes an application credential parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/delegated-grants: servers: [] get: operationId: listDelegatedGrants summary: List delegated grants tags: - Delegated Grants description: >- Returns a paginated list of delegated grants in the specified zone. Can be filtered by user, resource, or status. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending. Use `expand[]=total_count` to include the matching row count. parameters: - schema: type: string in: query name: user_id required: false description: Filter by user ID - schema: type: string in: query name: resource_id required: false description: Filter by resource ID - schema: type: string enum: - 'true' in: query name: active required: false - schema: type: string enum: - active - expired - revoked in: query name: status required: false - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: pattern: ^-?created_at(,\s*-?created_at)*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_DelegatedGrant' pagination: $ref: '#/components/schemas/iam_Pagination' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/delegated-grants/{id}: servers: [] get: operationId: getDelegatedGrant summary: Get delegated grant tags: - Delegated Grants description: Returns details of a specific delegated grant by grant ID parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Delegated grant ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- User authorization for a resource to be accessed on their behalf. The grant links the user, resource, and the provider that issued the grant. content: application/json: schema: $ref: '#/components/schemas/iam_DelegatedGrant' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateDelegatedGrant summary: Update delegated grant tags: - Delegated Grants description: Revokes an active delegated grant requestBody: content: application/json: schema: type: object required: - status properties: status: type: string enum: - revoked required: true parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Delegated grant ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- User authorization for a resource to be accessed on their behalf. The grant links the user, resource, and the provider that issued the grant. content: application/json: schema: $ref: '#/components/schemas/iam_DelegatedGrant' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteDelegatedGrant summary: Delete delegated grant tags: - Delegated Grants description: >- Permanently revokes a delegated grant, removing the user's access to the protected resource parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Delegated grant ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/external-sync-tokens: servers: [] get: operationId: listExternalSyncTokens summary: List external sync tokens tags: - External Sync Tokens description: >- Returns the external sync tokens for a zone, newest first. Token values are never returned; the value is available only in the response that created the token. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_ExternalSyncToken' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createExternalSyncToken summary: Create external sync token tags: - External Sync Tokens description: >- Creates a token an identity provider can use to provision users into this zone over SCIM. The zone must have `external_sync_enabled` set and a `user_identity_provider_id` configured; otherwise the request fails with 400. The token value is returned only in this response and cannot be retrieved later. Multiple tokens can be active at once: to rotate, create a new token, then delete the old one. parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A new external sync token, including the token value. The value is returned only in this response. content: application/json: schema: $ref: '#/components/schemas/iam_ExternalSyncTokenCreateResponse' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/external-sync-tokens/{id}: servers: [] get: operationId: getExternalSyncToken summary: Get external sync token tags: - External Sync Tokens description: >- Returns an external sync token's metadata. The token value is never returned. parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: External sync token ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- Token an identity provider uses to provision users and groups into a zone over SCIM. The token value is returned once, when the token is created, and is never returned again. content: application/json: schema: $ref: '#/components/schemas/iam_ExternalSyncToken' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteExternalSyncToken summary: Delete external sync token tags: - External Sync Tokens description: >- Deletes an external sync token. The token stops working immediately and cannot be restored — create a new one instead. parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: External sync token ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/providers: servers: [] get: operationId: listProviders summary: List providers tags: - Providers description: >- Returns a paginated list of providers in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending. Use `expand[]=total_count` to include the matching row count. Filter by exact slug via `filter[slug]`, exact identifier via `filter[identifier]` and provider type via `filter[type]`. Search via `query[name]` / `query[identifier]` / `query[]` (substring match, OR'd across repeated values). `query[]` matches against name and identifier. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of provider IDs — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested provider that exists in the zone, in a single page. Unknown or malformed IDs are silently omitted. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: query name: slug required: false - schema: type: string in: query name: identifier required: false - schema: type: string enum: - external - keycard-vault - keycard-sts in: query name: type required: false - schema: anyOf: - description: Filter by exact provider slug type: string - maxItems: 100 type: array items: type: string in: query name: filter[slug] required: false - schema: anyOf: - description: Filter by exact provider identifier type: string - maxItems: 100 type: array items: type: string in: query name: filter[identifier] required: false - schema: anyOf: - type: string enum: - external - keycard-vault - keycard-sts description: Filter by provider type - maxItems: 100 type: array items: type: string enum: - external - keycard-vault - keycard-sts in: query name: filter[type] required: false - schema: anyOf: - description: >- Restrict results to providers with this ID. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by name (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[name] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[identifier] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search across name and identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: pattern: ^-?(created_at|name|identifier)(,\s*-?(created_at|name|identifier))*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, name, identifier - schema: type: string in: query name: cursor required: false - schema: type: string in: path name: zoneId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - page_info - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Provider' page_info: allOf: - $ref: '#/components/schemas/iam_PageInfo' deprecated: true description: >- Deprecated: read cursor state from `pagination` instead. This field is retained for backward compatibility and will be removed in a future version. pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createProvider summary: Create provider tags: - Providers description: >- Creates a new Provider - a system that supplies access to Resources and allows actors to authenticate requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ProviderCreate' parameters: - schema: type: string in: path name: zoneId required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. content: application/json: schema: $ref: '#/components/schemas/iam_Provider' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/providers/{id}: servers: [] get: operationId: getProvider summary: Get provider tags: - Providers description: Returns details of a specific Provider by ID parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. content: application/json: schema: $ref: '#/components/schemas/iam_Provider' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateProvider summary: Update provider tags: - Providers description: Updates a Provider's configuration and metadata requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ProviderUpdate' parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. content: application/json: schema: $ref: '#/components/schemas/iam_Provider' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteProvider summary: Delete provider tags: - Providers description: Permanently deletes a provider parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/providers/{id}/validate: servers: [] post: operationId: validateProvider summary: Validate provider connection tags: - Providers description: >- Runs on-demand OIDC connection checks (issuer reachability, metadata retrieval, endpoint consistency, authorization endpoint reachability, and a demonstration client_credentials exchange) against the provider and returns a per-check result. Results are not persisted. parameters: - schema: type: string in: path name: zoneId required: true - schema: type: string in: path name: id required: true security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- Result of running the provider OIDC connection checks on demand. Not persisted. content: application/json: schema: $ref: '#/components/schemas/iam_ProviderValidationResult' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '502': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '504': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/resources: servers: [] get: operationId: listResources summary: List resources tags: - Resources description: >- Returns a paginated list of resources in the specified zone. Use cursor pagination via `after`/`before`, and `expand[]=total_count` to include the matching row count. Filter by exact identifier via `filter[identifier]`. Filter by trait via `filter[traits]` (repeated params are OR'd) or `filter[traits][all]` (contains-all). The scalar `identifier` query parameter is a backward-compatible alias for `filter[identifier]`: exact match on a single value, folded into the same exact-match identifier filter. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: anyOf: - description: Filter by exact resource slug type: string - maxItems: 100 type: array items: type: string in: query name: filter[slug] required: false - schema: anyOf: - description: Filter by exact resource identifier type: string - maxItems: 100 type: array items: type: string in: query name: filter[identifier] required: false - schema: anyOf: - description: >- Restrict results to resources with this publicId. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by name (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[name] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[identifier] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search across name and identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: pattern: ^-?(created_at|updated_at|name|identifier)(,\s*-?(created_at|updated_at|name|identifier))*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, updated_at, name, identifier - schema: type: string enum: - platform - customer in: query name: filter[owner_type] required: false description: >- Filter by owner type: `platform` (Keycard-managed) or `customer` (org-created). - schema: type: string in: query name: identifier required: false description: >- Backward-compatible alias for `filter[identifier]`: exact match on a single resource identifier. - schema: type: string in: query name: credentialProviderId required: false description: Filter resources by credential provider ID - schema: type: string in: query name: slug required: false - schema: anyOf: - type: string - maxItems: 100 type: array items: type: string in: query name: filter[traits] required: false description: >- Filter by trait. Repeated params are OR'd; each value is a single literal trait (a comma is a literal character). Use `filter[traits][all]` for contains-all. - schema: anyOf: - description: >- Resources that are not a dependency of this application. Repeatable (none of), max 100. type: string - maxItems: 100 type: array items: type: string in: query name: filter[dependency_of_application_id][ne] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Resource' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Default Response content: application/json: schema: type: object required: - message properties: message: type: string '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createResource summary: Create resource tags: - Resources description: >- Creates a new Resource - a system that exposes protected information or functionality requiring authentication requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ResourceCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Resource is a system that exposes protected information or functionality. It requires authentication of the requesting actor, which may be a user or application, before allowing access. content: application/json: schema: $ref: '#/components/schemas/iam_Resource' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/resources/{id}: servers: [] get: operationId: getResource summary: Get resource tags: - Resources description: Returns details of a specific Resource by ID parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Resource ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Resource is a system that exposes protected information or functionality. It requires authentication of the requesting actor, which may be a user or application, before allowing access. content: application/json: schema: $ref: '#/components/schemas/iam_Resource' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateResource summary: Update resource tags: - Resources description: Updates a Resource's configuration and metadata requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_ResourceUpdate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Resource ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A Resource is a system that exposes protected information or functionality. It requires authentication of the requesting actor, which may be a user or application, before allowing access. content: application/json: schema: $ref: '#/components/schemas/iam_Resource' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteResource summary: Delete resource tags: - Resources description: Permanently deletes a Resource parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Resource ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/roles: servers: [] get: operationId: listRoles summary: List roles tags: - Zone Roles description: >- Returns the roles defined in the specified zone, cursor-paginated. Ordered by identifier. parameters: - schema: type: string in: query name: identifier required: false description: Filter roles by identifier - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Role' pagination: $ref: '#/components/schemas/iam_Pagination' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createRole summary: Create role tags: - Zone Roles description: >- Creates a new customer-owned role in the specified zone. The owner_type is always customer; platform roles are managed by Keycard. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_RoleCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '201': description: A role that can be assigned to users within a zone. content: application/json: schema: $ref: '#/components/schemas/iam_Role' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/roles/{roleId}: servers: [] get: operationId: getRole summary: Get role tags: - Zone Roles description: Returns details of a specific role by ID parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: roleId required: true description: Role ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: A role that can be assigned to users within a zone. content: application/json: schema: $ref: '#/components/schemas/iam_Role' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateRole summary: Update role tags: - Zone Roles description: >- Updates a customer-owned role's description. The identifier is immutable, and platform-owned roles cannot be modified. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_RoleUpdate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: roleId required: true description: Role ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: A role that can be assigned to users within a zone. content: application/json: schema: $ref: '#/components/schemas/iam_Role' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteRole summary: Delete role tags: - Zone Roles description: >- Permanently deletes a customer-owned role. Platform-owned roles cannot be deleted, and a role with existing assignments returns 409. parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: roleId required: true description: Role ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/users/{userId}/roles: servers: [] get: operationId: listUserRoleAssignments summary: List user role assignments tags: - Zone Roles description: >- Returns the roles assigned to the specified user within the zone. Use cursor pagination via `after`/`before`; pass `expand[]=total_count` to include the matching row count. Pass `filter[scope_id]` (repeatable, max 100) to keep only the assignments scoped to those targets, and `filter[scoped]=false` to keep only unscoped assignments (the ones applying to the zone itself), so a known set of targets resolves in a fixed number of requests. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: anyOf: - description: >- Restrict results to assignments scoped to this target ID (e.g. a zone ID). Repeatable, max 100; values are OR'd. Unscoped assignments never match. type: string - maxItems: 100 type: array items: type: string in: query name: filter[scope_id] required: false - schema: type: boolean in: query name: filter[scoped] required: false description: >- `false` keeps only unscoped assignments (those applying to the zone itself, e.g. an org role); `true` keeps only scoped ones. Omit to list both. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: userId required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_RoleAssignment' pagination: $ref: '#/components/schemas/iam_Pagination' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: assignUserRole summary: Assign role to user tags: - Zone Roles description: >- Assigns a role to the user. Provide exactly one of role_id or role_identifier; when role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types (and must be omitted with role_id). An optional (scope_type, scope_id) pair scopes the grant; only platform roles on the org zone may carry a scope, and a `zone` scope must reference a different zone in the same organization. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignmentCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: userId required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '201': description: Represents a role assigned to a principal within a zone content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignment' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/users/{userId}/role-assignments: servers: [] get: operationId: listUserRoleAssignmentsByScope summary: List user role assignments by scope tags: - Zone Roles description: >- Returns the user's role assignments keyed by the scopes named in the request: one group per `scope_id[]` value (empty when the user holds nothing on it) plus, with `unscoped=true`, the group of assignments applying to the zone itself. Not paginated — the response has exactly as many groups as the request named, so a known set of up to 100 targets always resolves in one request. Use `GET …/roles` to enumerate everything the user holds. parameters: - schema: default: zone type: string in: query name: scope_type required: false description: >- The kind of resource the requested `scope_id[]` values name; echoed as each group's `scope_type`. Defaults to `zone`, the only scope type a grant can carry today. - schema: maxItems: 100 type: array items: type: string in: query name: scope_id[] required: false description: >- Scope IDs (of `scope_type`) to answer for. Repeatable, max 100; each yields exactly one group, empty when the principal holds nothing on it. Unknown IDs yield an empty group. - schema: default: false type: boolean in: query name: unscoped required: false description: >- `true` adds the unscoped group (grants applying to the zone itself, e.g. an org role) as the first item. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: userId required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- Role assignments keyed by requested scope. Not paginated: the number of groups equals the number of scopes named in the request. content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignmentScopeGroupList' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/users/{userId}/roles/{roleId}: servers: [] delete: operationId: revokeUserRole summary: Revoke role from user tags: - Zone Roles description: >- Revokes a role from the user. Provide the same (scope_type, scope_id) pair the grant was created with, or omit both to revoke the unscoped grant. parameters: - schema: minLength: 1 type: string in: query name: scope_type required: false description: Scope kind of the grant to revoke. Provide together with scope_id. - schema: minLength: 1 type: string in: query name: scope_id required: false description: >- Scope target of the grant to revoke. Provide together with scope_type. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: userId required: true description: User ID - schema: type: string in: path name: roleId required: true description: Role ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{applicationId}/roles: servers: [] get: operationId: listApplicationRoleAssignments summary: List application role assignments tags: - Zone Roles description: >- Returns the roles assigned to the specified application within the zone. Use cursor pagination via `after`/`before`; pass `expand[]=total_count` to include the matching row count. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: applicationId required: true description: Application ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_RoleAssignment' pagination: $ref: '#/components/schemas/iam_Pagination' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: assignApplicationRole summary: Assign role to application tags: - Zone Roles description: >- Assigns a role to the application. Provide exactly one of role_id or role_identifier; when role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types (and must be omitted with role_id). An optional (scope_type, scope_id) pair scopes the grant; only platform roles on the org zone may carry a scope, and a `zone` scope must reference a different zone in the same organization. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignmentCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: applicationId required: true description: Application ID security: - bearerAuth: [] - OAuth2: [] responses: '201': description: Represents a role assigned to a principal within a zone content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignment' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/applications/{applicationId}/roles/{roleId}: servers: [] delete: operationId: revokeApplicationRole summary: Revoke role from application tags: - Zone Roles description: >- Revokes a role from the application. Provide the same (scope_type, scope_id) pair the grant was created with, or omit both to revoke the unscoped grant. parameters: - schema: minLength: 1 type: string in: query name: scope_type required: false description: Scope kind of the grant to revoke. Provide together with scope_id. - schema: minLength: 1 type: string in: query name: scope_id required: false description: >- Scope target of the grant to revoke. Provide together with scope_type. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: applicationId required: true description: Application ID - schema: type: string in: path name: roleId required: true description: Role ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups: servers: [] get: operationId: listGroups summary: List groups tags: - Groups description: >- Returns a paginated list of the groups in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending (allowed: created_at, name, identifier). Pass `expand[]=member_count` to include each group's member count, `expand[]=roles` to include the identifiers of the roles assigned to each group, and `expand[]=total_count` to include the matching row count. Filter by exact identifier via `filter[identifier]` (repeatable, OR'd across values). Search via `query[]` (case-insensitive substring match, OR'd across repeated values); it matches the group's name and identifier. Pass `filter[external]=false` for only groups managed in Keycard or `filter[external]=true` for only groups synced from an external directory; omit it to list both. Filter externally synced groups by their directory issuer via `filter[external_issuer]` (exact match, repeatable, OR'd across values). Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of groups — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested group that exists in the zone, in a single page. IDs not in the zone are silently omitted. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - member_count - roles - type: array items: type: string enum: - total_count - member_count - roles in: query name: expand[] required: false - schema: anyOf: - description: >- Restrict results to groups with this ID. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - description: Filter by exact group identifier type: string - maxItems: 100 type: array items: type: string in: query name: filter[identifier] required: false - schema: type: boolean in: query name: filter[external] required: false description: >- Filter by source: `false` for groups managed in Keycard, `true` for groups synced from an external directory. Omit to list both. - schema: anyOf: - description: >- Filter by exact `external_issuer`: the issuer of the external directory the group was synced from. Groups managed in Keycard have no `external_issuer` and never match. type: string - maxItems: 100 type: array items: type: string in: query name: filter[external_issuer] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search across name and identifier (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: pattern: ^-?(created_at|name|identifier)(,\s*-?(created_at|name|identifier))*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, name, identifier - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Group' pagination: $ref: '#/components/schemas/iam_Pagination' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: createGroup summary: Create group tags: - Groups description: >- Creates a group in the zone (managed in Keycard). Groups synced from an external directory are created by that directory, not here. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_GroupCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '201': description: >- A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. content: application/json: schema: $ref: '#/components/schemas/iam_Group' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups/{groupId}: servers: [] get: operationId: getGroup summary: Get group tags: - Groups description: >- Returns a group by ID. Pass `expand[]=member_count` for its member count and `expand[]=roles` for the identifiers of its assigned roles. parameters: - schema: anyOf: - type: string enum: - member_count - roles - type: array items: type: string enum: - member_count - roles in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. content: application/json: schema: $ref: '#/components/schemas/iam_Group' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateGroup summary: Update group tags: - Groups description: >- Updates a group's name and/or identifier (partial update). A group's source is immutable. The name of a group synced from an external directory cannot be changed while external sync is enabled for the zone; its identifier can. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_GroupUpdate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. content: application/json: schema: $ref: '#/components/schemas/iam_Group' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteGroup summary: Delete group tags: - Groups description: >- Deletes a group and its memberships and role assignments. Groups synced from an external directory can only be deleted by that directory (after external sync is disabled). parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups/{groupId}/members: servers: [] get: operationId: listGroupMembers summary: List group members tags: - Groups description: >- Returns a paginated list of the group's members. Use cursor pagination via `after`/`before`. Pass `expand[]=user` to embed each member's full user record and `expand[]=total_count` to include the matching row count. Pass `query[]` (repeatable, 1-255 chars) to search members by their user's email or `subject` (substring match, OR'd across repeated values). Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of members by user ID — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested member that exists in the group, in a single page. IDs not in the group are silently omitted. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - user - type: array items: type: string enum: - total_count - user in: query name: expand[] required: false - schema: anyOf: - description: >- Restrict results to the member with this user ID. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: >- Search members by their user's email or `subject` (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_GroupMember' pagination: $ref: '#/components/schemas/iam_Pagination' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: addGroupMember summary: Add group member tags: - Groups description: >- Adds a user to a group managed in Keycard. Membership of externally synced groups is not managed manually. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_GroupMemberCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '201': description: A user's membership in a group content: application/json: schema: $ref: '#/components/schemas/iam_GroupMember' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups/{groupId}/members/{userId}: servers: [] delete: operationId: removeGroupMember summary: Remove group member tags: - Groups description: >- Removes a user from a group managed in Keycard. Membership of externally synced groups is not managed manually. A member is identified by its user's ID. parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID - schema: type: string in: path name: userId required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups/{groupId}/roles: servers: [] get: operationId: listGroupRoleAssignments summary: List group role assignments tags: - Groups description: >- Returns the roles assigned to the group. Members inherit these roles. Returns the shared role-assignment shape with `principal_type` set to `group`. Use cursor pagination via `after`/`before`; pass `expand[]=total_count` to include the matching row count. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of role assignments, mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested assignment that exists on the group, in a single page. IDs not on the group are silently omitted. Pass `filter[scope_id]` (repeatable, max 100) to keep only the assignments scoped to those targets, and `filter[scoped]=false` to keep only unscoped assignments (the ones applying to the zone itself). parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: anyOf: - description: >- Restrict results to the role assignment with this ID. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - description: >- Restrict results to assignments scoped to this target ID (e.g. a zone ID). Repeatable, max 100; values are OR'd. Unscoped assignments never match. type: string - maxItems: 100 type: array items: type: string in: query name: filter[scope_id] required: false - schema: type: boolean in: query name: filter[scoped] required: false description: >- `false` keeps only unscoped assignments (those applying to the zone itself, e.g. an org role); `true` keeps only scoped ones. Omit to list both. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_RoleAssignment' pagination: $ref: '#/components/schemas/iam_Pagination' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' post: operationId: assignGroupRole summary: Assign role to group tags: - Groups description: >- Assigns a role to the group; members inherit it. Provide role_id, or role_identifier with owner_type. Returns the shared role-assignment shape with `principal_type` set to `group`. requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignmentCreate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '201': description: Represents a role assigned to a principal within a zone content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignment' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups/{groupId}/role-assignments: servers: [] get: operationId: listGroupRoleAssignmentsByScope summary: List group role assignments by scope tags: - Groups description: >- Returns the group's role assignments keyed by the scopes named in the request: one group per `scope_id[]` value (empty when the group holds nothing on it) plus, with `unscoped=true`, the group of assignments applying to the zone itself. Not paginated — the response has exactly as many groups as the request named, so a known set of up to 100 targets always resolves in one request. Use `GET …/roles` to enumerate everything the group holds. parameters: - schema: default: zone type: string in: query name: scope_type required: false description: >- The kind of resource the requested `scope_id[]` values name; echoed as each group's `scope_type`. Defaults to `zone`, the only scope type a grant can carry today. - schema: maxItems: 100 type: array items: type: string in: query name: scope_id[] required: false description: >- Scope IDs (of `scope_type`) to answer for. Repeatable, max 100; each yields exactly one group, empty when the principal holds nothing on it. Unknown IDs yield an empty group. - schema: default: false type: boolean in: query name: unscoped required: false description: >- `true` adds the unscoped group (grants applying to the zone itself, e.g. an org role) as the first item. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- Role assignments keyed by requested scope. Not paginated: the number of groups equals the number of scopes named in the request. content: application/json: schema: $ref: '#/components/schemas/iam_RoleAssignmentScopeGroupList' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/groups/{groupId}/roles/{roleId}: servers: [] delete: operationId: revokeGroupRole summary: Revoke role from group tags: - Groups description: >- Revokes a role from the group. Provide the same (scope_type, scope_id) pair the grant was created with, or omit both to revoke the unscoped grant. parameters: - schema: minLength: 1 type: string in: query name: scope_type required: false description: Scope kind of the grant to revoke. Provide together with scope_id. - schema: minLength: 1 type: string in: query name: scope_id required: false description: >- Scope target of the grant to revoke. Provide together with scope_type. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: groupId required: true description: Group ID - schema: type: string in: path name: roleId required: true description: Role ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/session-resource-access: servers: [] get: operationId: listSessionResourceAccessByFilters summary: List aggregated session resource access tags: - Sessions description: >- Returns aggregated access records per session-resource pair. By default (rollup_children=true), includes access from descendant sessions. Set rollup_children=false to return only direct session access. At least one of user_id, session_id, or resource_id must be provided. parameters: - schema: type: string in: query name: user_id required: false description: Filter by user ID - schema: type: string in: query name: session_id required: false description: Filter by session ID - schema: type: string in: query name: resource_id required: false description: Filter by resource ID - schema: default: true type: boolean in: query name: rollup_children required: false description: >- Include resource access from descendant sessions. When true (default), aggregates access from the session and all its descendants. When false, returns only direct access for the session. - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: $ref: '#/components/schemas/iam_SessionResourceAccessList' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/sessions: servers: [] get: operationId: listSessions summary: List sessions tags: - Sessions description: >- Returns sessions in the specified zone. By default, returns entry sessions (app user sessions with an initiator that are roots or direct children of a root user session). Use include_nested=true to include nested sessions. Can be filtered by session type, status, and user. parameters: - schema: type: string enum: - user - application in: query name: session_type required: false - schema: type: string enum: - 'true' in: query name: active required: false - schema: type: string enum: - active - expired - revoked in: query name: status required: false - schema: type: string in: query name: user_id required: false description: Filter by user ID - schema: type: string enum: - 'true' in: query name: include_nested required: false description: >- Include nested sessions. When false (default), only returns entry sessions (direct children of root user sessions). When true, returns all sessions with an initiator, including nested sessions. - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_Session' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/sessions/{id}: servers: [] get: operationId: getSession summary: Get session tags: - Sessions description: Returns details of a specific session by session ID parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Session ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- An authenticated identity session. Sessions can be user sessions (representing end-user authentication) or application sessions (representing service-to-service authentication). User sessions support hierarchical relationships via parent_id, while application sessions are always standalone. content: application/json: schema: $ref: '#/components/schemas/iam_Session' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateSession summary: Update session tags: - Sessions description: Revokes an active session requestBody: content: application/json: schema: type: object required: - status properties: status: type: string enum: - revoked required: true parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Session ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- An authenticated identity session. Sessions can be user sessions (representing end-user authentication) or application sessions (representing service-to-service authentication). User sessions support hierarchical relationships via parent_id, while application sessions are always standalone. content: application/json: schema: $ref: '#/components/schemas/iam_Session' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteSession summary: Delete session tags: - Sessions description: >- Permanently deletes a session, effectively logging out the user or application parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: Session ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/user-agents: servers: [] get: operationId: listUserAgents summary: List user agents tags: - User Agents description: >- Returns the user agents in the specified zone, cursor-paginated and ordered by name. User agents represent client software (browsers, desktop apps, CLI tools) registered via OAuth 2.0 Dynamic Client Registration. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of user agents — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested user agent that exists in the zone, in a single page. IDs not in the zone are silently omitted. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - type: array items: type: string enum: - total_count in: query name: expand[] required: false - schema: anyOf: - description: >- Restrict results to user agents with this ID. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - description: Filter by exact identifier (OAuth client_id) type: string - maxItems: 100 type: array items: type: string in: query name: filter[identifier] required: false - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_UserAgent' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/user-agents/{id}: servers: [] get: operationId: getUserAgent summary: Get user agent tags: - User Agents description: Returns details of a specific user agent by user agent ID parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: User agent ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: >- A User Agent represents a user agent (browser, desktop app, CLI tool) that can initiate user sessions via OAuth 2.0 Dynamic Client Registration. content: application/json: schema: $ref: '#/components/schemas/iam_UserAgent' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/users: servers: [] get: operationId: listUsers summary: List users tags: - Users description: >- Returns a paginated list of users in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending. Use `expand[]=total_count` to include the matching row count, `expand[]=session_count` to include per-user session counts, `expand[]=grant_count` to include per-user delegated-grant counts, `expand[]=role-assignments` to include each user's structured role grants (direct grants only by default, each tagged with `source`; use `role_source=all` to also include group-inherited), `expand[]=groups` to include each user's group memberships, `expand[]=credentials` to include each user's authentication credentials (each with its `provider_id`), and `expand[]=credentials.provider` to additionally inline the full identity provider on each federation credential. Filter by exact email via `filter[email]` and by exact identifier via `filter[identifier]`; restrict to members of a group via `filter[groups]` (repeatable, OR'd across values); restrict to users directly granted a role via `filter[role]` (role identifier, repeatable up to 100, OR'd across values; group-inherited grants do not match); pass `filter[external]=false` for only users managed in Keycard or `filter[external]=true` for only users provisioned by an external directory (omit to list both); match exactly on the user's `subject` and `issuer` via `filter[subject]` and `filter[issuer]` (each repeatable and OR'd across values; AND'd with each other); search via `query[email]` / `query[subject]` / `query[]` (substring match, OR'd across repeated values). `query[]` matches against email and the user's `subject`. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of users — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested user that exists in the zone, in a single page. IDs not in the zone are silently omitted. parameters: - schema: minLength: 1 maxLength: 255 type: string in: query name: after required: false description: Cursor for forward pagination - schema: minLength: 1 maxLength: 255 type: string in: query name: before required: false description: Cursor for backward pagination - schema: minimum: 1 maximum: 100 default: 20 type: integer in: query name: limit required: false description: Maximum number of items to return - schema: anyOf: - type: string enum: - total_count - session_count - grant_count - role-assignments - groups - credentials - credentials.provider - type: array items: type: string enum: - total_count - session_count - grant_count - role-assignments - groups - credentials - credentials.provider in: query name: expand[] required: false - schema: type: string enum: - user - group - all in: query name: role_source required: false description: >- Selects which grants `expand[]=role-assignments` returns, tagging each with `source`: `user` (direct only, the default), `group` (group-inherited only), or `all` (both direct and group-inherited). Requires `expand[]=role-assignments`. - schema: anyOf: - format: email description: Filter by exact email address type: string - maxItems: 100 type: array items: format: email type: string in: query name: filter[email] required: false - schema: anyOf: - description: >- Restrict results to users with this publicId. Repeatable, max 100. Mutually exclusive with after/before. type: string - maxItems: 100 type: array items: type: string in: query name: filter[id] required: false - schema: anyOf: - description: Filter by exact user identifier type: string - maxItems: 100 type: array items: type: string in: query name: filter[identifier] required: false - schema: anyOf: - description: >- Restrict to members of this group (by group ID). Repeatable; OR'd across values. type: string - maxItems: 100 type: array items: type: string in: query name: filter[groups] required: false - schema: anyOf: - description: >- Restrict to users directly granted this role (by role identifier). Repeatable, max 100; OR'd across values. Group-inherited grants do not match. type: string - maxItems: 100 type: array items: type: string in: query name: filter[role] required: false - schema: type: boolean in: query name: filter[external] required: false description: >- Filter by source: `false` for users managed in Keycard, `true` for users provisioned by an external directory. Omit to list both. - schema: anyOf: - description: Filter by exact `subject`. Repeatable; OR'd across values. type: string - maxItems: 100 type: array items: type: string in: query name: filter[subject] required: false - schema: anyOf: - description: Filter by exact `issuer`. Repeatable; OR'd across values. type: string - maxItems: 100 type: array items: type: string in: query name: filter[issuer] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by email (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[email] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search by the user's `subject` (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[subject] required: false - schema: anyOf: - minLength: 1 maxLength: 255 description: Search across email and the user's `subject` (substring match) type: string - maxItems: 100 type: array items: minLength: 1 maxLength: 255 type: string in: query name: query[] required: false - schema: pattern: ^-?(created_at|email|authenticated_at)(,\s*-?(created_at|email|authenticated_at))*$ type: string in: query name: sort required: false description: >- Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, email, authenticated_at - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: Default Response content: application/json: schema: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/iam_User' pagination: $ref: '#/components/schemas/iam_Pagination' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/users/{id}: servers: [] get: operationId: getUser summary: Get user tags: - Users description: >- Returns details of a specific user by user ID. Use `expand[]=role-assignments` for the user's structured role grants and `expand[]=groups` for the user's group memberships. Role grants are direct only by default, each tagged with `source`; use `role_source=all` to also include group-inherited. parameters: - schema: anyOf: - type: string enum: - role-assignments - groups - type: array items: type: string enum: - role-assignments - groups in: query name: expand[] required: false - schema: type: string enum: - user - group - all in: query name: role_source required: false description: >- Selects which grants `expand[]=role-assignments` returns, tagging each with `source`: `user` (direct only, the default), `group` (group-inherited only), or `all` (both direct and group-inherited). Requires `expand[]=role-assignments`. - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: An authenticated user entity content: application/json: schema: $ref: '#/components/schemas/iam_User' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' patch: operationId: updateUser summary: Update user tags: - Users description: Update a user requestBody: content: application/json: schema: $ref: '#/components/schemas/iam_UserUpdate' parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: An authenticated user entity content: application/json: schema: $ref: '#/components/schemas/iam_User' '400': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' delete: operationId: deleteUser summary: Delete user tags: - Users description: Delete a user parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID - schema: type: string in: path name: id required: true description: User ID security: - bearerAuth: [] - OAuth2: [] responses: '204': description: Default Response '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '409': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /zones/{zoneId}/users/me: servers: [] get: operationId: getCurrentUser summary: Get current user tags: - Users description: >- Returns the currently authenticated user in the zone. Requires read access to the resolved user. Returns 404 when the caller has no user record in the zone. parameters: - schema: type: string in: path name: zoneId required: true description: Zone ID security: - bearerAuth: [] - OAuth2: [] responses: '200': description: An authenticated user entity content: application/json: schema: $ref: '#/components/schemas/iam_User' '403': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' '404': description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/iam_Error' /organizations: servers: [] post: operationId: createOrganization parameters: - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Organization details to create content: application/json: schema: $ref: '#/components/schemas/org-management_CreateOrganizationRequest' responses: '201': description: Organization created successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Organization' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '409': description: Organization with label already exists headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organizations security: - bearerAuth: [] - OAuth2: [] get: operationId: listOrganizations description: List organizations for the current user parameters: - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' - in: query name: after description: Cursor for forward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: before description: Cursor for backward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: limit description: Maximum number of organizations to return schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: List of organizations headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_OrganizationsList' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organizations security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}: servers: [] get: operationId: getOrganization description: Get organization by ID or label parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' responses: '200': description: Organization details headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Organization' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organizations security: - bearerAuth: [] - OAuth2: [] patch: operationId: updateOrganization description: Update organization details parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Organization update details required: true content: application/json: schema: $ref: '#/components/schemas/org-management_UpdateOrganizationRequest' responses: '200': description: Organization updated successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Organization' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '409': description: Organization with label already exists headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organizations security: - bearerAuth: [] - OAuth2: [] delete: operationId: deleteOrganization summary: Delete organization by ID or label description: | Deletes the organization and all zones. parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '204': description: Organization deleted successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organizations security: - bearerAuth: [] - OAuth2: [] /service-account-token: servers: [] post: operationId: postServiceAccountToken description: > Exchange service account credentials for an organization-scoped M2M token. Credentials may be provided via HTTP Basic Authentication (RFC 6749 Section 2.3.1, preferred) or as form body parameters. The server MUST NOT accept credentials in both locations simultaneously and will reject such requests with a 400 error. security: [] parameters: - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: OAuth2 Client Credentials required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type properties: grant_type: type: string enum: - client_credentials description: OAuth 2.0 grant type (must be "client_credentials") client_id: type: string nullable: true description: >- Service account client ID. Required if not using HTTP Basic Authentication. client_secret: type: string nullable: true description: >- Service account client secret. Required if not using HTTP Basic Authentication. responses: '200': description: M2M token generated successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_TokenResponse' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Accounts /organizations/{organization_id}/invitations: servers: [] post: operationId: createOrganizationInvitation description: Create an invitation to join an organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Invitation details required: true content: application/json: schema: $ref: '#/components/schemas/org-management_CreateInvitationRequest' responses: '201': description: Invitation created successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Invitation' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '409': description: Pending invitation already exists for this email headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organization Invitations security: - bearerAuth: [] - OAuth2: [] get: operationId: listOrganizationInvitations description: List invitations for an organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' - in: query name: after description: Cursor for forward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: before description: Cursor for backward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: limit description: Maximum number of invitations to return schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query name: filter[status] description: > Return only invitations with these statuses. Repeat the parameter to match any of several statuses (`?filter[status]=pending&filter[status]=accepted`). Expired invitations are never listed, so `expired` matches nothing. When absent, no status filter is applied. required: false style: form explode: true schema: type: array minItems: 1 maxItems: 4 items: $ref: '#/components/schemas/org-management_InvitationStatus' responses: '200': description: List of organization invitations headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_InvitationsList' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organization Invitations security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}/invitations/{invitation_id}: servers: [] delete: operationId: deleteOrganizationInvitation description: Delete an invitation parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: invitation_id required: true description: Invitation ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '204': description: Invitation deleted headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organization Invitations security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}/service-accounts: servers: [] post: operationId: createServiceAccount description: Create a new service account for an organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Service account details required: true content: application/json: schema: $ref: '#/components/schemas/org-management_CreateServiceAccountRequest' responses: '201': description: Service account created successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccount' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Accounts security: - bearerAuth: [] - OAuth2: [] get: operationId: listServiceAccounts description: List service accounts for an organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' - in: query name: query[] description: > Search service accounts by name or description (case-insensitive substring match). When multiple values are provided, a service account matches if it matches any of them. required: false style: form explode: true schema: type: array maxItems: 10 items: type: string minLength: 1 maxLength: 255 - in: query name: after description: Cursor for forward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: before description: Cursor for backward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: limit description: Maximum number of service accounts to return schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: List of service accounts headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccountsList' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Accounts security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}/service-accounts/{service_account_id}: servers: [] get: operationId: getServiceAccount description: Get a specific service account parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' responses: '200': description: Service account details headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccount' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Accounts security: - bearerAuth: [] - OAuth2: [] patch: operationId: updateServiceAccount description: Update a service account parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Service account update details required: true content: application/json: schema: $ref: '#/components/schemas/org-management_UpdateServiceAccountRequest' responses: '200': description: Service account updated successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccount' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Accounts security: - bearerAuth: [] - OAuth2: [] delete: operationId: deleteServiceAccount description: Delete a service account parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '204': description: Service account deleted headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Accounts security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}/service-accounts/{service_account_id}/credentials: servers: [] post: operationId: createServiceAccountCredential description: Create a new credential for a service account parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Credential creation details content: application/json: schema: $ref: '#/components/schemas/org-management_CreateServiceAccountCredentialRequest' responses: '201': description: Credential created successfully (client_secret is only shown once) headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccountCredentialWithSecret' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Account Credentials security: - bearerAuth: [] - OAuth2: [] get: operationId: listServiceAccountCredentials description: List credentials for a service account parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' - in: query name: query[] description: > Search credentials by name, client ID, or description (case-insensitive substring match). When multiple values are provided, a credential matches if it matches any of them. required: false style: form explode: true schema: type: array maxItems: 10 items: type: string minLength: 1 maxLength: 255 - in: query name: after description: Cursor for forward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: before description: Cursor for backward pagination schema: $ref: '#/components/schemas/org-management_Cursor' - in: query name: limit description: Maximum number of credentials to return schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: List of credentials (without secrets) headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccountCredentialsList' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Account Credentials security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}/service-accounts/{service_account_id}/credentials/{credential_id}: servers: [] get: operationId: getServiceAccountCredential description: Get a specific service account credential parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - in: path name: credential_id required: true description: Credential ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' responses: '200': description: Credential details (without secret) headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccountCredential' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Account Credentials security: - bearerAuth: [] - OAuth2: [] patch: operationId: updateServiceAccountCredential description: Update a service account credential parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - in: path name: credential_id required: true description: Credential ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: Credential update details required: true content: application/json: schema: $ref: '#/components/schemas/org-management_UpdateServiceAccountCredentialRequest' responses: '200': description: Credential updated successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_ServiceAccountCredential' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Account Credentials security: - bearerAuth: [] - OAuth2: [] delete: operationId: deleteServiceAccountCredential description: Delete a service account credential parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - in: path name: service_account_id required: true description: Service account ID schema: $ref: '#/components/schemas/org-management_ShortID' - in: path name: credential_id required: true description: Credential ID schema: $ref: '#/components/schemas/org-management_ShortID' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '204': description: Credential deleted headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Service Account Credentials security: - bearerAuth: [] - OAuth2: [] /invitations/{token}: servers: [] get: operationId: getInvitationByToken description: View invitation details by token without consuming the token security: [] parameters: - in: path name: token required: true description: Invitation token schema: type: string minLength: 1 maxLength: 500 pattern: ^[A-Za-z0-9_.-]+$ - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '200': description: Invitation details headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_InvitationDetails' '400': $ref: '#/components/responses/org-management_BadRequestError' '404': $ref: '#/components/responses/org-management_NotFoundError' '410': description: Invitation has expired or already been consumed headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organization Invitations /invitations/{token}/accept: servers: [] post: operationId: acceptInvitation description: Accept and consume an invitation token to join the organization parameters: - in: path name: token required: true description: Invitation token schema: type: string minLength: 1 maxLength: 500 pattern: ^[A-Za-z0-9_.-]+$ - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '200': description: Invitation accepted successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_InvitationAcceptResult' '400': $ref: '#/components/responses/org-management_BadRequestError' '403': description: Email mismatch or invitation cannot be accepted by current user headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '404': $ref: '#/components/responses/org-management_NotFoundError' '410': description: Invitation has expired or already been consumed headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - Organization Invitations security: - bearerAuth: [] - OAuth2: [] /organizations/{organization_id}/sso-connection: servers: [] post: operationId: enableSSOConnection description: Enable SSO for organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: SSO connection configuration required: true content: application/json: schema: $ref: '#/components/schemas/org-management_SSOConnectionCreate' responses: '201': description: SSO connection created successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_SSOConnection' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': $ref: '#/components/responses/org-management_NotFoundError' '409': description: SSO is already enabled for this organization headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - SSO Connection security: - bearerAuth: [] - OAuth2: [] get: operationId: getSSOConnection description: Get SSO connection configuration for organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' - $ref: '#/components/parameters/org-management_Expand' responses: '200': description: SSO connection details headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_SSOConnection' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': description: Organization not found or SSO not enabled headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - SSO Connection security: - bearerAuth: [] - OAuth2: [] patch: operationId: updateSSOConnection description: Update SSO connection configuration parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' requestBody: description: SSO connection update details required: true content: application/json: schema: $ref: '#/components/schemas/org-management_SSOConnectionUpdate' responses: '200': description: SSO connection updated successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_SSOConnection' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': description: Organization not found or SSO not enabled headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - SSO Connection security: - bearerAuth: [] - OAuth2: [] delete: operationId: disableSSOConnection description: Disable SSO for organization parameters: - in: path name: organization_id required: true description: Organization ID or label schema: $ref: '#/components/schemas/org-management_OrganizationIdOrLabel' - $ref: '#/components/parameters/org-management_X-Client-Request-ID' responses: '204': description: SSO connection disabled successfully headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' '400': $ref: '#/components/responses/org-management_BadRequestError' '401': $ref: '#/components/responses/org-management_UnauthorizedError' '403': $ref: '#/components/responses/org-management_ForbiddenError' '404': description: Organization not found or SSO not enabled headers: X-Request-ID: $ref: '#/components/headers/org-management_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/org-management_Error' '429': $ref: '#/components/responses/org-management_RateLimitExceededError' '500': $ref: '#/components/responses/org-management_InternalServerError' '503': $ref: '#/components/responses/org-management_ServiceUnavailableError' default: $ref: '#/components/responses/org-management_InternalServerError' tags: - SSO Connection security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-schemas: servers: [] get: operationId: listPolicySchemas summary: List policy schemas tags: - PolicySchemas x-authz: action: list resourceType: policy_schemas scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_Expand' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_SchemaFormat' - $ref: '#/components/parameters/pdp_IsDefault' - $ref: '#/components/parameters/pdp_FilterDefault' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policy schemas headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySchemasList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-schemas/{version}: servers: [] get: operationId: getPolicySchema summary: Get a policy schema by version tags: - PolicySchemas x-authz: action: read resource: param: version type: policy_schemas scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_SchemaVersionParam' - $ref: '#/components/parameters/pdp_SchemaFormat' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The requested policy schema headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_SchemaVersionWithZoneInfo' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] patch: operationId: setDefaultPolicySchema summary: Set the default policy schema for a zone tags: - PolicySchemas x-authz: action: update resource: param: version type: policy_schemas scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_SchemaVersionParam' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/pdp_SetDefaultPolicySchemaRequest' responses: '200': description: The updated policy schema headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_SchemaVersionWithZoneInfo' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policies: servers: [] get: operationId: listPolicies summary: List policies in a zone description: | Returns a paginated list of policies in the zone. Supports cursor-based pagination, sorting, full-text search, and composable filters. The `filter[id]` parameter restricts results to a known set of policy IDs (up to 100). It composes with other filters (`filter[owner_type]`, `query[]`, etc.) but **cannot** be combined with cursor pagination (`after` / `before`) — the server returns 400 if both are present. When `filter[id]` is used without an explicit `limit`, the limit defaults to the number of requested IDs so all results fit in a single page. IDs that don't exist or fall outside the zone are silently omitted. tags: - Policies x-authz: action: list resourceType: policies scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_Expand' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_QueryName' - $ref: '#/components/parameters/pdp_QueryDescription' - $ref: '#/components/parameters/pdp_QueryUnscoped' - $ref: '#/components/parameters/pdp_Query' - $ref: '#/components/parameters/pdp_FilterOwnerType' - $ref: '#/components/parameters/pdp_FilterID' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policies headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PoliciesList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] post: operationId: createPolicy summary: Create a new policy tags: - Policies x-authz: action: create resourceType: policies scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_CreatePolicyRequest' responses: '201': description: The newly created policy headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_Policy' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '409': description: Conflict - a policy with this name already exists headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policies/{policy_id}: servers: [] get: operationId: getPolicy summary: Get a policy by ID tags: - Policies x-authz: action: read resource: param: policy_id type: policies scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_ExpandSingle' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The requested policy headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_Policy' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] patch: operationId: updatePolicy summary: Update a policy tags: - Policies x-authz: action: update resource: param: policy_id type: policies scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_If-Match' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_UpdatePolicyRequest' responses: '200': description: The updated policy headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_Policy' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: Conflict - name collision headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '412': description: >- Precondition Failed - resource has been modified since the provided ETag headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: archivePolicy summary: Archive a policy tags: - Policies x-authz: action: delete resource: param: policy_id type: policies scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The archived policy headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_Policy' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policies/{policy_id}/versions: servers: [] get: operationId: listPolicyVersions summary: List versions of a policy tags: - PolicyVersions x-authz: action: list resourceType: policy_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_Expand' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_PolicyFormat' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policy versions headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyVersionsList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] post: operationId: createPolicyVersion summary: Create a new immutable policy version tags: - PolicyVersions x-authz: action: create resourceType: policy_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_CreatePolicyVersionRequest' responses: '201': description: The newly created policy version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policies/{policy_id}/versions/{version_id}: servers: [] get: operationId: getPolicyVersion summary: Get a specific policy version tags: - PolicyVersions x-authz: action: read resource: param: version_id type: policy_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_VersionId' - $ref: '#/components/parameters/pdp_PolicyFormat' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_ExpandSingle' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The requested policy version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: archivePolicyVersion summary: Archive a policy version tags: - PolicyVersions x-authz: action: delete resource: param: version_id type: policy_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_VersionId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The archived policy version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-validations: servers: [] post: operationId: validatePolicyContent summary: Validate Cedar policy content against a schema tags: - PolicyValidations x-authz: action: evaluate resourceType: policy_validations scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_ValidatePolicyContentRequest' responses: '200': description: Validation result headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyValidationResult' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policies/{policy_id}/draft: servers: [] get: operationId: getPolicyDraft summary: Get the draft for a policy tags: - PolicyDrafts x-authz: action: read resource: param: policy_id type: policy_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_PolicyFormat' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_ExpandSingle' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The policy draft headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyDraft' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] put: operationId: upsertPolicyDraft summary: Create or update a policy draft tags: - PolicyDrafts x-authz: action: create resource: param: policy_id type: policy_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - name: format in: query required: false description: >- Response format override. `json` returns cedar_json, `cedar` returns cedar_raw. When omitted, the response matches the input format. schema: type: string enum: - cedar - json - name: validate_cedar in: query required: false schema: type: boolean default: true description: Whether to validate cedar_json against the schema. Defaults to true. - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_UpsertPolicyDraftRequest' responses: '200': description: The upserted policy draft headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyDraft' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: Conflict - concurrency conflict headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: deletePolicyDraft summary: Delete a policy draft tags: - PolicyDrafts x-authz: action: delete resource: param: policy_id type: policy_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicyId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '204': description: Draft successfully deleted headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets: servers: [] get: operationId: listPolicySets summary: List policy sets in a zone description: | Returns a paginated list of policy sets in the zone. `filter[target_type]` defaults to `zone`, hiding principal-scoped sets (e.g. per-user bundle sets) unless explicitly widened. The deprecated `filter[scope_type]` is honored as an equivalent and suppresses the default; supplying both with different value sets returns 400. tags: - PolicySets x-authz: action: list resourceType: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_Expand' - $ref: '#/components/parameters/pdp_ExpandNew' - name: sort in: query required: false description: | Field to sort by. `created_at` (default) sorts by creation date. `status` sorts active-first, then by creation date within each group. When `sort=status`, only descending order and forward pagination are supported; `order=asc` or `before` cursors return 400. schema: type: string enum: - created_at - status default: created_at - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_QueryName' - $ref: '#/components/parameters/pdp_QueryUnscoped' - $ref: '#/components/parameters/pdp_Query' - $ref: '#/components/parameters/pdp_FilterOwnerType' - $ref: '#/components/parameters/pdp_FilterScopeType' - $ref: '#/components/parameters/pdp_FilterTargetType' - $ref: '#/components/parameters/pdp_FilterActive' - $ref: '#/components/parameters/pdp_FilterActiveNew' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policy sets headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetsList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] post: operationId: createPolicySet summary: Create a new policy set description: > Creates a policy set. Supply `manifest` to create its first version and any new policies in the same transaction. A failure rolls back every write. Without `manifest`, creates a versionless set and preserves the existing response body. Entries use manifest apply semantics with no predecessor: bare pins use each policy's latest version; supplied content reuses that version when its SHA and schema match. Omitted `schema_version` uses the zone default. This operation supports neither `dry_run` nor `If-Match`. Set `manifest.activate: true` to bind v1 to the zone's active slot in the same transaction. Requires `target_type: zone` (the default) and the `activate` permission on `policy_set_bindings`, in addition to the route's `create` permission. Omitted or false leaves the set unbound. The `ETag` header is the set revision, as on `GET`. The manifest digest is `policy_set_version.manifest_sha` and the `ETag` of `GET .../manifest`. Domain error codes: `policy_set_name_conflict`, `policy_name_conflict`, `policy_not_found`, `policy_archived`, `policy_version_not_found`, `version_archived`, `schema_version_mismatch`, `manifest_duplicate_policy`, `missing_cedar_content`, `invalid_cedar`, `schema_version_unsupported`, `activate_requires_zone_target`. tags: - PolicySets x-authz: action: create resourceType: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_CreatePolicySetRequest' responses: '201': description: The newly created policy set headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetWithBinding' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: >- A policy or policy set name conflicts, or a referenced policy is archived headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}: servers: [] get: operationId: getPolicySet summary: Get a policy set by ID description: Returns the policy set with current binding information. tags: - PolicySets x-authz: action: read resource: param: policy_set_id type: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_ExpandSingle' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The requested policy set with binding info headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetWithBinding' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] patch: operationId: updatePolicySet summary: Update a policy set description: >- Update policy set metadata (name). Binding is managed by activating a policy set version or via the policy-bindings API. tags: - PolicySets x-authz: action: update resource: param: policy_set_id type: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_If-Match' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_UpdatePolicySetRequest' responses: '200': description: The updated policy set headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetWithBinding' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: Conflict - concurrency conflict or name collision headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '412': description: >- Precondition Failed - resource has been modified since the provided ETag headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: archivePolicySet summary: Archive a policy set tags: - PolicySets x-authz: action: delete resource: param: policy_set_id type: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_If-Match' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The archived policy set headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetWithBinding' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: >- Conflict - policy set is currently bound. Bind a replacement policy set to the slot (or delete the shadow binding), then archive. headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '412': description: >- Precondition Failed - resource has been modified since the provided ETag headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/versions: servers: [] get: operationId: listPolicySetVersions summary: List versions of a policy set tags: - PolicySetVersions x-authz: action: list resourceType: policy_set_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_Expand' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policy set versions headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersionsList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] post: operationId: createPolicySetVersion summary: Create a new immutable policy set version description: >- Validates the manifest, computes SHA, and creates an immutable version snapshot. tags: - PolicySetVersions x-authz: action: create resourceType: policy_set_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_CreatePolicySetVersionRequest' responses: '201': description: The newly created policy set version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}: servers: [] get: operationId: getPolicySetVersion summary: Get a specific policy set version tags: - PolicySetVersions x-authz: action: read resource: param: version_id type: policy_set_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_VersionId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_ExpandSingle' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The requested policy set version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] patch: operationId: updatePolicySetVersion summary: Activate a policy set version description: Set active=true to bind this version as the active zone policy set. tags: - PolicySetVersions x-authz: action: update resource: param: version_id type: policy_set_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_VersionId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_UpdatePolicySetVersionRequest' responses: '200': description: The policy set version, now active headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: archivePolicySetVersion summary: Archive a policy set version tags: - PolicySetVersions x-authz: action: delete resource: param: version_id type: policy_set_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_VersionId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The archived policy set version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersion' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}/policies: servers: [] get: operationId: listPolicySetVersionPolicies summary: List policy versions in a policy set version description: >- Returns the policy versions referenced by this policy set version's manifest as a paginated list. tags: - PolicySetVersions x-authz: action: list resourceType: policy_set_versions scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_VersionId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_Expand' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_PolicyFormat' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policy versions in this policy set version headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersionPoliciesList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/draft: servers: [] post: operationId: createPolicySetDraft summary: Create or resume a policy set draft description: >- Safe draft creation that never overwrites an existing draft. If a draft already exists for this policy set, it is returned as-is (200 OK). Three body modes control how a new draft is initialized: (1) empty body — hydrate from the latest non-archived version, (2) { base_version_id } — hydrate from a specific version, (3) full body with manifest and schema_version — create with explicit content. base_version_id and manifest are mutually exclusive; providing both is rejected. tags: - PolicySetDrafts x-authz: action: create resource: param: policy_set_id type: policy_set_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/pdp_CreatePolicySetDraftRequest' responses: '200': description: Existing draft resumed (unchanged) headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetDraft' '201': description: New draft created headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetDraft' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] get: operationId: getPolicySetDraft summary: Get the draft for a policy set tags: - PolicySetDrafts x-authz: action: read resource: param: policy_set_id type: policy_set_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_ExpandSingle' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The policy set draft headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetDraft' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] put: operationId: upsertPolicySetDraft summary: Create or replace a policy set draft description: >- Full replacement of the draft state. Creates the draft if it does not exist, replaces it if it does. Standard REST PUT idempotency — the caller provides the complete desired state. tags: - PolicySetDrafts x-authz: action: create resource: param: policy_set_id type: policy_set_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_UpsertPolicySetDraftRequest' responses: '200': description: The upserted policy set draft headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetDraft' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: Conflict - concurrency conflict headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] patch: operationId: patchPolicySetDraft summary: Partially update a policy set draft description: >- Applies partial updates to an existing draft. Supports updating metadata fields (name, description, schema_version) and manifest operations (set, add, remove entries). tags: - PolicySetDrafts x-authz: action: update resource: param: policy_set_id type: policy_set_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_PatchPolicySetDraftRequest' responses: '200': description: The updated policy set draft headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetDraft' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: Conflict - concurrency conflict headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: deletePolicySetDraft summary: Delete a policy set draft tags: - PolicySetDrafts x-authz: action: delete resource: param: policy_set_id type: policy_set_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '204': description: Draft successfully deleted headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/draft/policies: servers: [] get: operationId: listPolicySetDraftPolicies summary: List policies in a policy set draft description: >- Returns the policy versions referenced by the draft's manifest as a paginated list. Mirrors the published `/policy-sets/{policy_set_id}/versions/{version_id}/policies` endpoint but sources entries from the policy set's mutable draft. Archived policy versions referenced by the manifest are still returned. tags: - PolicySetDrafts x-authz: action: read resource: param: policy_set_id type: policy_set_drafts scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_PolicyFormat' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of policy versions pinned by this draft's manifest headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetVersionPoliciesList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/clones: servers: [] post: operationId: clonePolicySet summary: Clone a policy set into a new customer-owned set description: | Creates a new customer-owned policy set whose first version reproduces the manifest of a source version: the source's latest non-archived version by default, or the one named by `source_version_id`. The set, any copied policies and their versions, the first policy set version, and its attestation are written in one transaction. Any failure leaves zero writes. The source is never modified. Platform-owned sets (for example the zone default `default-zone-policies`) cannot be updated or versioned by customers. Clone is how a customer forks one into a set they can edit with `PUT .../manifest`. `copy_policies` decides what is shared and what is duplicated (default `platform`): - `none`: every entry pins the same policy version as the source. No new policies are created. - `platform`: platform-owned pins are copied into new customer-owned policies; customer-owned pins are shared. The result is fully editable with minimal duplication. - `all`: every pin is copied. Copied policies get `owner_type: customer`, the source policy's description, and a first version whose `cedar_json`, `schema_version` and `sha` are copied verbatim from the pinned source version. There is no Cedar revalidation and no rewrite of the embedded static-policy keys; the evaluator namespaces them by policy version ID. A copied policy is named after its source, with the platform catalog prefix `default-` stripped for platform-owned sources (`default-user-grants` becomes `user-grants`). Customer-owned names are kept as-is. A derived name that collides with a non-archived policy in the zone gets the first free numeric suffix (`user-grants-2`, `user-grants-3`, ...). Names are resolved inside the transaction; a concurrent race still surfaces as `409 policy_name_conflict`. Manifest order is the source's, with shared and copied pins interleaved as they were. `schema_version` is the source version's. `target_type` defaults to the source set's and may be overridden. The `ETag` header is the digest of the first version's manifest, so clone, then conditional `PUT .../manifest`, needs no intermediate GET. Domain error codes: `policy_set_not_found`, `policy_set_version_not_found`, `policy_set_name_conflict`, `policy_name_conflict`, `set_archived`, `version_archived`, `schema_version_unsupported`. tags: - PolicySets x-authz: action: create resourceType: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_ClonePolicySetRequest' responses: '201': description: The new policy set, its first version, and the per-policy outcome headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: description: | Digest of the new set's first (and latest) manifest. Usable as `If-Match` on a follow-up `PUT .../manifest` without a re-GET. schema: type: string content: application/json: schema: $ref: '#/components/schemas/pdp_ClonePolicySetResult' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': description: | Source set not found (`policy_set_not_found`), or `source_version_id` names a version that does not exist on it (`policy_set_version_not_found`). headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '409': description: | `policy_set_name_conflict` (`name` already exists in the zone), `policy_name_conflict` (a derived policy name lost a race), `set_archived`, `version_archived` (the source version is archived, or it pins an archived policy version), or `schema_version_unsupported` (the source version's schema is archived; clone a newer source version). headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-sets/{policy_set_id}/manifest: servers: [] get: operationId: getPolicySetManifest summary: Get the manifest of a policy set version description: | Returns the resolved manifest of the **latest non-archived version** by default. Pass `?version=` with a policy set version public ID to read a specific version's manifest (e.g. for rollback: GET an old manifest, PUT it back — which mints a new version at the tip with the old content; history is never re-pointed). There is deliberately no `?version=active` keyword: a binding slot is `(zone, target_type, target_id, mode)` and a set may have zero or several active bindings, so "the active version" is not a function of the set alone. Resolve the version ID first — from the enriched policy set representation (`active_version_id`) or `GET /policy-bindings` — then pass it here. The default (latest) read anchors the apply flow: the `ETag` response header is the JCS SHA-256 digest of the latest manifest and is the value to send as `If-Match` on `PUT`. **`ETag` is emitted only on the default latest read** — versioned reads return `manifest_sha` in the body but no `ETag`, so a stale token cannot be round-tripped as a precondition. A policy set with no versions yet returns `200` with empty `entries`, null `policy_set_version_id`/`version`/`schema_version`/`manifest_sha`, and the digest of the empty manifest as `ETag`, so even the first apply can be conditional. tags: - PolicySetManifest x-authz: action: read resource: param: policy_set_id type: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' - name: version in: query required: false schema: type: string description: 'Policy set version public ID. Default: latest non-archived version.' responses: '200': description: The resolved manifest headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetManifestDetail' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': description: >- Policy set not found (`policy_set_not_found`), or `?version=` names a version that does not exist (`policy_set_version_not_found`). headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] put: operationId: applyPolicySetManifest summary: Apply the full desired state of a policy set description: > Declarative full-replace apply. `entries` is the complete desired content of the policy set: **any policy omitted from `entries` is dropped from the resulting version** (its rows are retained and a later apply may reference it again). Entry order is preserved for newly added policies; retained policies keep their current manifest order, so an unchanged apply is byte-identical and dedups to the existing version. Per entry, the server diffs by content SHA against the version pinned in the latest manifest: unchanged content under the same schema version reuses the pinned policy version; changed content mints a new policy version; `new_policy` entries mint a customer-owned policy with the requested name. All of this, plus the policy set version mint and the optional activation, happens in **one transaction** (row lock on the policy set). Cedar validation runs against the resolved schema before the transaction opens — an invalid policy rejects the whole apply with zero writes. **Schema resolution:** `schema_version` omitted → the latest version's schema if still writable, else the zone default. Provided → authoritative (`schema_version_unsupported` if unknown, unattested, or archived). All entries validate against the single resolved version (uniform-schema-per-version is retained); a pinned policy version created under a different schema is re-versioned even if its content is unchanged. **Activation:** `activate: true` requires a zone-targeted set and rebinds the `(zone, target_type=zone, mode=active)` slot to the resulting version in the same transaction. It requires `policy_set_bindings:activate` permission and preserves the previous binding in binding history. Unchanged content returns `created: false` and still activates the resulting version. An already active version keeps its binding unchanged. **Concurrency:** `If-Match` is optional (omitted = last-writer-wins). When provided it is compared, under the row lock, against the digest of the latest version's manifest; mismatch returns `412` (`etag_mismatch`) carrying the current `ETag`. The token is content-addressed, not a version identity: it guards "the content I read is still the content in place", so two versions with identical manifests are interchangeable for the precondition, and archiving the tip does not invalidate a token whose digest the new latest version still carries. Do not re-key it on `policy_set_version_id`. **Identity and reverts:** a desired state identical to the **latest** version is a no-op (`created: false`, latest returned, nothing minted). A desired state matching an **older** version mints a new version at the tip — history is linear, never forked. Rolling back deployment without a content edit is not an apply at all: bind the older version via `PUT /policy-bindings`. **Authorization:** the route gate is `update` on the policy set. When `activate: true`, the handler additionally requires the `activate` action on `policy_set_bindings`. Domain error codes: `policy_set_not_found`, `policy_not_found`, `policy_version_not_found`, `version_archived`, `schema_version_mismatch`, `manifest_duplicate_policy`, `missing_cedar_content`, `invalid_cedar`, `schema_version_unsupported`, `policy_name_conflict`, `policy_archived`, `set_archived`, `etag_mismatch`, `activate_requires_zone_target`, `shadow_equals_active`. tags: - PolicySetManifest x-authz: action: update resource: param: policy_set_id type: policy_sets scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_PolicySetId' - $ref: '#/components/parameters/pdp_If-Match' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' - name: dry_run in: query required: false schema: type: boolean default: false description: >- Not yet implemented — `true` returns 501 until ACC-1002. When true, performs validation, schema resolution, and the content diff, and returns the would-be `changes` and `warnings` — but persists nothing. `policy_set_version` is omitted from the response and no ETag is returned. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_ApplyPolicySetManifestRequest' responses: '200': description: >- The apply result. Always `200` — the resulting version may be newly minted (`created: true`), deduped to an existing version, or a pure no-op (`created: false`); the body discriminates so clients never branch on status. headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: description: >- Digest of the resulting (now latest) manifest — usable as If-Match for a follow-up apply without a re-GET. Omitted on dry_run. schema: type: string content: application/json: schema: $ref: '#/components/schemas/pdp_ApplyPolicySetManifestResult' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': description: >- Caller lacks the route permission, or `activate: true` and the caller lacks the `activate` permission on policy set bindings — the error names the missing permission. headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '404': $ref: '#/components/responses/pdp_NotFoundError' '409': description: >- Conflict: `policy_name_conflict` (a `new_policy` name already exists in the zone), `policy_archived`, `set_archived`. headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '412': description: >- Precondition failed (`etag_mismatch`): the latest manifest no longer matches `If-Match`. The current `ETag` is returned so the client can re-read, merge, and retry. headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' ETag: $ref: '#/components/headers/pdp_ETag' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-evaluations: servers: [] post: operationId: createPolicyEvaluation summary: Test Cedar policy evaluation against real entities description: > Stateless evaluation endpoint for testing Cedar policy evaluation against real entities before deployment. Supports evaluating a single policy, a full policy set, or raw Cedar text. tags: - PolicyEvaluations x-authz: action: evaluate resourceType: policy_evaluations scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyEvaluationRequest' responses: '200': description: The evaluation result headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicyEvaluationResponse' '400': description: > Bad Request - invalid input or validation error. Common causes: - Schema validation error (action/principal/resource doesn't exist in schema) - Entity not found (invalid principal_id, subject_id, or resource_id) - Policy source error (policy/policy set/version not found, draft doesn't exist) - Unsupported schema version - Invalid Cedar policy syntax (when using 'raw' source with validate=true) headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_Error' examples: schema_validation_error: summary: Action doesn't exist in schema value: status: 400 code: validation_error message: policy evaluation validation error request_id: 8fdccf3e-655c-918c-be90-5caf8efde53d timestamp: '2026-03-31T10:02:00Z' path: /zones/4yscgiw2iynj3hfeenuxa3q6gp/policy-evaluations details: - field: policy_source message: >- check 0: action `Keycard::Action::"invalid_action"` does not exist in the supplied schema code: validation_error entity_not_found: summary: Principal not found value: status: 400 code: bad_request message: 'user not found: invalid_user_id' request_id: 8fdccf3e-655c-918c-be90-5caf8efde53d timestamp: '2026-03-31T10:02:00Z' path: /zones/4yscgiw2iynj3hfeenuxa3q6gp/policy-evaluations details: - field: principal_id message: 'user not found: invalid_user_id' code: bad_request '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-evaluations/requests: servers: [] get: operationId: listEvaluationRequests summary: List captured evaluation requests description: > Returns a paginated list of evaluation request entries captured from live credentials API traffic for the specified zone. Sorted by created_at descending (newest first). Use with the test evaluation endpoint for replay-based impact analysis. tags: - PolicyEvaluations x-authz: action: list resourceType: policy_evaluations scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_After' - $ref: '#/components/parameters/pdp_Before' - $ref: '#/components/parameters/pdp_Limit' - $ref: '#/components/parameters/pdp_ExpandNew' - $ref: '#/components/parameters/pdp_Sort' - $ref: '#/components/parameters/pdp_Order' - $ref: '#/components/parameters/pdp_QueryAction' - $ref: '#/components/parameters/pdp_FilterActiveDecision' - $ref: '#/components/parameters/pdp_FilterPrincipalType' - $ref: '#/components/parameters/pdp_FilterSubjectType' - $ref: '#/components/parameters/pdp_FilterAuthorityType' - $ref: '#/components/parameters/pdp_FilterHasShadow' - $ref: '#/components/parameters/pdp_FilterPrincipalId' - $ref: '#/components/parameters/pdp_FilterResourceId' - $ref: '#/components/parameters/pdp_FilterSubjectId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: A paginated list of evaluation requests headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_EvaluationRequestsList' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' '503': $ref: '#/components/responses/pdp_ServiceUnavailableError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-bindings: servers: [] put: operationId: setPolicyBinding summary: Create or replace a policy set binding description: > Upserts a binding for a slot identified by (scope_type, scope_target_id, mode). If a binding already exists for the slot, it is replaced. The binding ID is stable per slot and survives replacements. tags: - PolicyBindings x-authz: action: create resourceType: policy_set_bindings scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/pdp_SetPolicySetBindingRequest' responses: '200': description: The binding was created or replaced headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetBinding' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] get: operationId: listPolicyBindings summary: List policy set bindings for a zone description: | Returns bindings for the zone, filtered by target and mode. `filter[target_type]` defaults to `zone` and `filter[mode]` defaults to `shadow` when omitted (preserving the endpoint's historical shadow-only listing); pass explicit values to widen. The deprecated bare `scope_type` and `mode` parameters are honored as equivalents and suppress the respective defaults; supplying a bare parameter and its `filter[...]` form with different values returns 400. With an effective target type set of exactly `zone`, `filter[target_id]` values other than the zone ID return 400. tags: - PolicyBindings x-authz: action: list resourceType: policy_set_bindings scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' - name: scope_type in: query required: false deprecated: true schema: type: string enum: - zone description: | **Deprecated.** Use `filter[target_type]` instead. Still honored for backward compatibility but only accepts `zone`; other values return 400. Conflicts with `filter[target_type]` return 400. - name: mode in: query required: false deprecated: true schema: type: string enum: - shadow description: | **Deprecated.** Use `filter[mode]` instead. Still honored for backward compatibility but only accepts `shadow`; other values return 400. Conflicts with `filter[mode]` return 400. - $ref: '#/components/parameters/pdp_FilterTargetType' - $ref: '#/components/parameters/pdp_FilterTargetID' - $ref: '#/components/parameters/pdp_FilterMode' responses: '200': description: List of bindings headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/pdp_PolicySetBinding' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-bindings/{binding_id}: servers: [] get: operationId: getPolicyBinding summary: Get a policy set binding by ID description: Returns a specific binding by its stable identifier. tags: - PolicyBindings x-authz: action: read resource: param: binding_id type: policy_set_bindings scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_BindingId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '200': description: The binding headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetBinding' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] delete: operationId: deletePolicyBinding summary: Delete a policy set binding description: Removes a binding by its identifier, stopping evaluation for that slot. tags: - PolicyBindings x-authz: action: delete resource: param: binding_id type: policy_set_bindings scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_BindingId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' responses: '204': description: Binding deleted headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/policy-bindings/{binding_id}/metrics: servers: [] get: operationId: getPolicyBindingMetrics summary: Get shadow evaluation metrics for a binding description: > Returns shadow evaluation metrics for a specific binding. Use query parameters to change scope: - `scope=zone` — zone-level aggregate across all pairings - `psv_id=` — metrics for a specific policy set version (in any role), including per-pairing breakdown tags: - PolicyBindings x-authz: action: read resource: param: binding_id type: policy_set_bindings scope: zone: param: zone_id parameters: - $ref: '#/components/parameters/pdp_ZoneId' - $ref: '#/components/parameters/pdp_BindingId' - $ref: '#/components/parameters/pdp_X-API-Version' - $ref: '#/components/parameters/pdp_X-Client-Request-ID' - name: scope in: query required: false schema: type: string enum: - binding - zone default: binding description: | Metrics scope. `binding` (default) returns metrics for this binding. `zone` returns zone-level aggregate across all pairings. - name: policy_set_id in: query required: false schema: type: string description: Policy set to filter metrics for. Required when psv_id is provided. - name: psv_id in: query required: false schema: type: string description: >- Filter to a specific policy set version (in any role). When provided, response includes per-pairing breakdown. Requires policy_set_id. - name: since in: query required: false schema: type: string format: date-time description: Start of the time window (default 24h ago) responses: '200': description: Shadow evaluation metrics headers: X-Request-ID: $ref: '#/components/headers/pdp_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/pdp_PolicySetShadowMetricsSummary' '400': $ref: '#/components/responses/pdp_BadRequestError' '401': $ref: '#/components/responses/pdp_UnauthorizedError' '403': $ref: '#/components/responses/pdp_ForbiddenError' '404': $ref: '#/components/responses/pdp_NotFoundError' '429': $ref: '#/components/responses/pdp_RateLimitExceededError' '500': $ref: '#/components/responses/pdp_InternalServerError' default: $ref: '#/components/responses/pdp_InternalServerError' security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/secrets: servers: [] post: operationId: createZoneSecret x-authz: action: create resourceType: secrets scope: zone: param: zone_id parameters: - in: path name: zone_id required: true schema: $ref: '#/components/schemas/vault-api_ID' - $ref: '#/components/parameters/vault-api_X-Client-Request-ID' requestBody: description: A JSON object containing the secret's value that should be stored. required: true content: application/json: schema: $ref: '#/components/schemas/vault-api_CreateZoneSecretRequest' responses: '201': description: Secret created successfully headers: X-Request-ID: $ref: '#/components/headers/vault-api_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/vault-api_Secret' '400': $ref: '#/components/responses/vault-api_BadRequestError' '401': $ref: '#/components/responses/vault-api_UnauthorizedError' '403': $ref: '#/components/responses/vault-api_ForbiddenError' '429': $ref: '#/components/responses/vault-api_RateLimitExceededError' '500': $ref: '#/components/responses/vault-api_InternalServerError' '503': $ref: '#/components/responses/vault-api_ServiceUnavailableError' default: $ref: '#/components/responses/vault-api_InternalServerError' tags: - Secrets security: - bearerAuth: [] - OAuth2: [] get: operationId: listZoneSecrets x-authz: action: list resourceType: secrets scope: zone: param: zone_id parameters: - in: path name: zone_id required: true schema: $ref: '#/components/schemas/vault-api_ID' - in: query name: entity_id description: The entity to list all secrets for schema: type: string - in: query name: type description: The type of secrets to list. Required when owner_type is specified. schema: type: string enum: - token - password - in: query name: owner_type description: > Filter by secret ownership. Services can select either owner type; other principals can select only customer-owned secrets. If omitted, services see both owner types and other principals see customer-owned secrets. Requires type=token or type=password when specified. schema: $ref: '#/components/schemas/vault-api_SecretOwnerType' - $ref: '#/components/parameters/vault-api_X-Client-Request-ID' responses: '200': description: List available secrets without their decrypted values headers: X-Request-ID: $ref: '#/components/headers/vault-api_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/vault-api_SecretsList' '400': $ref: '#/components/responses/vault-api_BadRequestError' '401': $ref: '#/components/responses/vault-api_UnauthorizedError' '403': $ref: '#/components/responses/vault-api_ForbiddenError' '404': $ref: '#/components/responses/vault-api_NotFoundError' '429': $ref: '#/components/responses/vault-api_RateLimitExceededError' '500': $ref: '#/components/responses/vault-api_InternalServerError' '503': $ref: '#/components/responses/vault-api_ServiceUnavailableError' default: $ref: '#/components/responses/vault-api_InternalServerError' tags: - Secrets security: - bearerAuth: [] - OAuth2: [] /zones/{zone_id}/secrets/{id}: servers: [] delete: operationId: deleteZoneSecret x-authz: action: delete resource: param: id type: secrets scope: zone: param: zone_id parameters: - in: path name: zone_id required: true schema: $ref: '#/components/schemas/vault-api_ID' - in: path name: id required: true schema: type: string - $ref: '#/components/parameters/vault-api_X-Client-Request-ID' responses: '204': description: Secret deleted successfully headers: X-Request-ID: $ref: '#/components/headers/vault-api_X-Request-ID' '400': $ref: '#/components/responses/vault-api_BadRequestError' '401': $ref: '#/components/responses/vault-api_UnauthorizedError' '403': $ref: '#/components/responses/vault-api_ForbiddenError' '429': $ref: '#/components/responses/vault-api_RateLimitExceededError' '500': $ref: '#/components/responses/vault-api_InternalServerError' '503': $ref: '#/components/responses/vault-api_ServiceUnavailableError' default: $ref: '#/components/responses/vault-api_InternalServerError' tags: - Secrets security: - bearerAuth: [] - OAuth2: [] patch: operationId: updateZoneSecret x-authz: action: update resource: param: id type: secrets scope: zone: param: zone_id parameters: - in: path name: zone_id required: true schema: $ref: '#/components/schemas/vault-api_ID' - in: path name: id required: true schema: type: string - $ref: '#/components/parameters/vault-api_X-Client-Request-ID' requestBody: description: A JSON object containing the secret's value that should be stored. required: true content: application/json: schema: $ref: '#/components/schemas/vault-api_UpdateSecretRequest' responses: '200': description: Secret updated successfully headers: X-Request-ID: $ref: '#/components/headers/vault-api_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/vault-api_Secret' '400': $ref: '#/components/responses/vault-api_BadRequestError' '401': $ref: '#/components/responses/vault-api_UnauthorizedError' '403': $ref: '#/components/responses/vault-api_ForbiddenError' '429': $ref: '#/components/responses/vault-api_RateLimitExceededError' '500': $ref: '#/components/responses/vault-api_InternalServerError' '503': $ref: '#/components/responses/vault-api_ServiceUnavailableError' default: $ref: '#/components/responses/vault-api_InternalServerError' tags: - Secrets security: - bearerAuth: [] - OAuth2: [] get: operationId: getZoneSecretValue x-authz: action: read resource: param: id type: secrets scope: zone: param: zone_id parameters: - in: path name: zone_id required: true schema: $ref: '#/components/schemas/vault-api_ID' - in: path name: id required: true schema: type: string - $ref: '#/components/parameters/vault-api_X-Client-Request-ID' responses: '200': description: Secret value retrieved successfully headers: X-Request-ID: $ref: '#/components/headers/vault-api_X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/vault-api_SecretValue' '400': $ref: '#/components/responses/vault-api_BadRequestError' '401': $ref: '#/components/responses/vault-api_UnauthorizedError' '403': $ref: '#/components/responses/vault-api_ForbiddenError' '404': $ref: '#/components/responses/vault-api_NotFoundError' '429': $ref: '#/components/responses/vault-api_RateLimitExceededError' '500': $ref: '#/components/responses/vault-api_InternalServerError' '503': $ref: '#/components/responses/vault-api_ServiceUnavailableError' default: $ref: '#/components/responses/vault-api_InternalServerError' tags: - Secrets security: - bearerAuth: [] - OAuth2: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT Bearer Token Authentication OAuth2: type: oauth2 description: OAuth2 Client Credentials Authentication flows: clientCredentials: tokenUrl: /service-account-token scopes: {} schemas: common_Error: type: object description: Represents an error that has occurred in the Keycard system. properties: status: type: integer description: HTTP Status Code code: $ref: '#/components/schemas/common_ErrorCode' message: type: string description: summary of the error request_id: type: string format: uuid timestamp: type: string format: date-time path: type: string format: url details: type: array items: $ref: '#/components/schemas/common_ErrorDetail' additionalProperties: false required: - status - code - message - request_id - timestamp - path - details x-go-type: httperrors.Error x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/httperrors name: httperrors common_ErrorDetail: type: object properties: field: type: string description: >- valid json path for request body. Omitted when the detail is not tied to a request field (e.g. domain error codes); clients should treat absent and empty the same. message: type: string description: error message for specific error code: anyOf: - $ref: '#/components/schemas/common_ErrorCode' - type: string description: >- Machine-readable code. Either a common `ErrorCode` value or a service-specific domain code (snake_case) documented by the service's own API spec. Clients should match on this instead of parsing `message`. Open set; unknown codes must be tolerated. example: version_currently_bound required: - message - code additionalProperties: false x-go-type: httperrors.ErrorDetail x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/httperrors name: httperrors common_ErrorCode: type: string enum: - validation_error - bad_request - unauthorized - forbidden - not_found - conflict - rate_limit_exceeded - internal_error - not_implemented - service_unavailable x-enum-varnames: - ValidationErrorCode - BadRequestErrorCode - UnauthorizedErrorCode - ForbiddenErrorCode - NotFoundErrorCode - ConflictErrorCode - RateLimitExceededErrorCode - InternalErrorCode - NotImplementedErrorCode - ServiceUnavailableErrorCode x-go-type: httperrors.ErrorCode x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/httperrors name: httperrors common_ID: type: string description: A globally unique opaque identifier minLength: 1 x-go-type: types.ID x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_IdentityRef: type: object description: >- A reference to another entity including its ID and a href to fetch this entity. properties: id: $ref: '#/components/schemas/common_ID' href: type: string format: url required: - id - href additionalProperties: false x-go-type: types.IdentityRef x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Identifier: type: string description: >- An identifier representing either an opaque ID or address (labels separated by periods, e.g.: aws.s3) minLength: 1 x-go-type: types.IdentifierString x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Name: type: string description: A name for the entity to be displayed in UI pattern: ^[a-zA-Z][a-zA-Z0-9\s,\.'\-pL\ \-_]{1,63}$ x-go-type: types.Name x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Label: type: string description: A domain name segment for the entity, often derived from the name. pattern: ^([a-z0-9]+(-[a-z0-9]+)+)$ maxLength: 63 x-go-type: types.Label x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Address: type: string description: >- A domain address for the entity, derived from labels of parent entities (e.g. aws.s3) pattern: ^[a-z][a-z0-9\-]{2,64}(\.[a-z][a-z0-9\-]{2,64}){0,9}$ x-go-type: types.Address x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Description: type: string description: A description of the entity maxLength: 128 x-go-type: types.Description x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Tags: type: array description: An array of meta data to make searching for entities easier. items: type: string pattern: ^[a-z][a-z0-9\-\_\ \.]{1,63}$ description: A tag maxItems: 10 x-go-type: types.Tags x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Visibility: type: string description: >- The visibility of the entity and whether its publicly available, privately available to those who own it, or if its hidden entirely as a system resource. enum: - public - private - hidden x-go-type: types.Visibility x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_CreatedAt: type: string description: The time the entity was created in utc format: date-time common_UpdatedAt: type: string description: The time the entity was mostly recently updated in utc format: date-time common_IdentityType: type: string enum: - user - service_account x-go-type: types.IdentityType x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Domain: type: string format: hostname x-go-type: types.Domain x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Permission: type: string pattern: ^[a-zA-Z0-9_.:/+-]{3,128}$ description: A valid permission or scope made available on a ResourceType x-go-type: types.Permission x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_RestrictedSchema: type: object description: RestrictedSchema for specify the schema of a dynamic type or field externalDocs: description: JSON Metaschema for RestrictedSchema url: https://catalog.keycard.sh/schemas/restricted-schema-01.json additionalProperties: true x-go-type: types.RestrictedSchema x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_URITemplate: type: string description: An RFC6570 Level-4 Compatible URI Template maxLength: 256 externalDocs: description: RFC6570 Specification url: https://datatracker.ietf.org/doc/html/rfc6570#section-2 example: '{scheme}://{user}:{password}@{hostname}:{port}/{/dbname}' x-go-type: types.URITemplate x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_StringTemplate: type: string description: >- A simple string template that only supports simple variable replacement (e.g. \"hey {world}\"). example: hello {name}, how are you? maxLength: 256 x-go-type: types.StringTemplate x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_VariableName: type: string pattern: ^[a-z][a-z0-9_]{0,31}$ description: A string representing a variable name in a StringTemplate or URITemplate example: user_id x-go-type: types.VariableName x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_URL: type: string format: url description: RFC3986 compliant URL x-go-type: types.URL x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_PaginationCursor: type: string description: An opaque cursor used for paginating through a list of results minLength: 1 maxLength: 255 x-go-type: types.PaginationCursor x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_Pagination: type: object description: Cursor-based pagination metadata returned alongside a list of results properties: before_cursor: type: string nullable: true allOf: - $ref: '#/components/schemas/common_PaginationCursor' after_cursor: type: string nullable: true allOf: - $ref: '#/components/schemas/common_PaginationCursor' total_count: type: integer description: >- Total number of items across all pages. Only present when the request includes ?expand[]=total_count. required: - before_cursor - after_cursor additionalProperties: false x-go-type: types.Pagination x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types common_FilterValues: type: array description: | Value shape for `filter[]` query parameters. Wire conventions: - Repeated parameter instances are OR-ed across values. - A single value containing comma-separated tokens is AND-ed across tokens. Examples: ?filter[status]=a&filter[status]=b -> status in (a, b) ?filter[tag]=foo,bar -> tag contains foo AND bar ?filter[tag]=foo,bar&filter[tag]=baz -> (foo AND bar) OR baz Field names and allowed values are endpoint-specific; services declare each filter[] parameter per operation with an appropriate items.type/items.enum override. items: type: string common_QueryTerms: type: array description: | Value shape for `query[]` and `query[]` search parameters. Wire conventions: - Case-insensitive substring match (ILIKE). - Repeated parameter instances are OR-ed across terms. - Comma splitting is NOT performed; literal commas in a search term are preserved as part of the term. Examples: ?query[name]=alpha&query[name]=beta -> name ILIKE %alpha% OR name ILIKE %beta% ?query[]=alpha -> any searchable field ILIKE %alpha% Cross-field form is `query[]`; field-scoped form is `query[]`. Field names are endpoint-specific; services declare each query parameter per operation. items: type: string minLength: 1 maxLength: 255 pdp-credentials_PdpError: type: object required: - error - error_description properties: error: type: string description: PDP error code enum: - invalid_request - invalid_token - entity_not_found - no_active_binding - evaluation_error - internal_error error_description: type: string description: Human-readable error description request_id: type: string entity_type: type: string description: Present when error is entity_not_found entity_id: type: string description: Present when error is entity_not_found pdp_EvaluationContext: type: object description: | Additional context for Cedar authorization evaluation. Fields here are mapped directly into the Cedar `context` record. properties: scopes: type: array items: type: string description: | OAuth scopes associated with the request. Mapped to `context.scopes` in the Cedar evaluation as a `Set`. session_id: type: string description: | Session identifier for the current authorization context. Mapped to `context.session_id` in Cedar. claims: $ref: '#/components/schemas/pdp_EvaluationClaims' additionalProperties: false pdp_EvaluationClaims: type: object description: | Token claims for the actor, subject, and/or acting principal. Mapped to `context.actor_claims`, `context.subject_claims`, and `context.acting_principal_claims` in Cedar. properties: actor: $ref: '#/components/schemas/pdp_ClaimsData' subject: $ref: '#/components/schemas/pdp_ClaimsData' acting_principal: $ref: '#/components/schemas/pdp_ClaimsData' additionalProperties: false pdp_ClaimsData: type: object description: | Represents token claims passed into the Cedar context. Mapped to the Cedar `Keycard::Claims` type. Known fields (`email`, `groups`, `issuer_claims`) are typed; additional claims are passed through as untyped key-value pairs via `additionalProperties`. additionalProperties: true properties: email: type: string description: Email claim from the authentication token. groups: type: array items: type: string description: Group membership claims from the authentication token. issuer_claims: $ref: '#/components/schemas/pdp_IssuerClaims' pdp_IssuerClaims: type: object description: | Issuer-specific claims forwarded opaquely from STS (e.g. GHA OIDC assertion claims). Mapped to `context.actor_claims.issuer_claims` in Cedar. All fields are optional and issuer-dependent. See issuer documentation for available claim fields. additionalProperties: true pdp_EvaluationCheck: type: object description: | Result of a single Cedar sub-check within a compound evaluation. Each check's determining policies and their effect are attributed to that check's own decision, not the deny-wins aggregate. properties: role: type: string enum: - actor - subject description: | actor = the requesting principal's access (or its right to act for the subject in an on-behalf-of flow); subject = the impersonated / delegated principal's own access. decision: type: string enum: - allow - deny determining_policies: type: array items: $ref: '#/components/schemas/pdp_DeterminingPolicyDetail' additionalProperties: false pdp_DeterminingPolicyDetail: type: object description: | A policy that contributed to the decision, enriched with human-readable names and version. For an allow these are permit policies; for an explicit deny these are forbid policies. An implicit (fall-through) deny has none. On the management test-evaluate endpoint, names and policy-set version populate only when a minted policy version is being evaluated; raw text and draft sources stay structural. properties: policy_id: type: string description: Public ID of the policy. policy_name: type: string description: Human-readable policy name. rule_id: type: string description: | Cedar per-rule `@id` annotation that determined the decision (e.g. `limit-linear-scopes`). Falls back to the generated `policyN` key when the Cedar statement carries no `@id`. policy_version_id: type: string description: Public ID of the policy version that was evaluated. policy_set_id: type: string description: Public ID of the policy set the policy belongs to. policy_set_name: type: string description: Human-readable policy set name. policy_set_version: type: integer description: Version number of the policy set. effect: type: string enum: - permit - forbid additionalProperties: false pdp_DiagnosticEntry: type: object properties: policy_id: type: string message: type: string additionalProperties: false catalog_CatalogDependencyStatus: type: string enum: - attached - failed description: Whether attaching an application dependency succeeded. catalog_CatalogInstallDependency: type: object required: - resource_id properties: resource_id: type: string description: The svc-iam resource id to wire as a dependency. description: >- An existing in-zone resource to attach to a package install as a dependency. catalog_CatalogInstallDependencyResult: type: object required: - resource_id - status properties: resource_id: type: string description: The requested resource id. status: allOf: - $ref: '#/components/schemas/catalog_CatalogDependencyStatus' description: Whether the dependency was attached. error: type: string description: Error detail, present only when `status` is `failed`. description: The outcome of attaching one application dependency. catalog_CatalogInstallRequest: type: object properties: package_id: type: string description: >- Public ID of the package to install. Provide exactly one of package_id or slug. slug: type: string description: >- Stable slug of the package to install, resolved within the zone's visible catalog (most specific scope wins). Lets callers install a known package without discovering its per-zone package_id. Provide exactly one of package_id or slug; providing both is rejected. fields: type: object additionalProperties: {} description: Values for the package's form fields, keyed by field `name`. dependencies: type: array items: $ref: '#/components/schemas/catalog_CatalogInstallDependency' description: >- Existing in-zone resources to attach to the provisioned package as dependencies in the same call. Each is wired by resource id; a failure to attach one is reported per-item in the response `dependencies` without failing the install or the others. description: >- Request body for installing a package from the catalog. Exactly one of `package_id` or `slug` must be provided to identify the package; providing neither or both is rejected. oneOf: - required: - package_id - required: - slug catalog_CatalogInstallResponse: type: object properties: dependencies: type: array items: $ref: '#/components/schemas/catalog_CatalogInstallDependencyResult' description: >- Per-dependency outcomes for the request's `dependencies`, in request order. Absent when the install carried no dependencies. description: >- Response body for a catalog install. A synchronous install either succeeds or fails with an error; on success the provisioned entity's URL is returned in the `Location` header. `dependencies` carries the per-item attach outcomes when the request supplied any. catalog_CatalogPackage: type: object required: - id - slug - name - form - created_at - updated_at properties: id: type: string slug: type: string description: URL-friendly identifier. name: type: string description: type: string form: allOf: - $ref: '#/components/schemas/catalog_Form' description: The input required to install this package. created_at: type: string format: date-time updated_at: type: string format: date-time icon_url: type: string description: Fully-qualified CDN link for the package icon. setup_guide: allOf: - $ref: '#/components/schemas/catalog_Keycard.Catalog.Vocabulary.markdown' description: Markdown text describing how to set up the subject. usage_guide: allOf: - $ref: '#/components/schemas/catalog_Keycard.Catalog.Vocabulary.markdown' description: Markdown text explaining how to use the subject. recommended: type: boolean description: Boolean flag indicating whether the subject is recommended. categories: type: array items: type: string description: Array of category labels. icon: type: string description: Icon basename used by the catalog UI grid. tags: type: array items: type: string description: UI-facing tags surfaced by the catalog detail page. long_description: allOf: - $ref: '#/components/schemas/catalog_Keycard.Catalog.Vocabulary.markdown' description: Markdown long description shown on the catalog detail page. tools: type: array items: type: object properties: name: type: string description: type: string required: - name - description additionalProperties: type: string description: >- List of tool descriptors surfaced by the package. The kind of tool is implied by the subject's domain (e.g., MCP packages describe MCP tools). additionalProperties: {} description: Catalog installable item. catalog_CatalogPackageList: type: object required: - items - pagination properties: items: type: array items: $ref: '#/components/schemas/catalog_CatalogPackage' pagination: $ref: '#/components/schemas/catalog_Pagination' catalog_Form: type: object required: - fields properties: fields: type: array items: $ref: '#/components/schemas/catalog_FormField' description: Empty when the package can be installed without input. description: Describes the input a user must supply to install a package. catalog_FormField: type: object required: - type - label - name - required properties: type: allOf: - $ref: '#/components/schemas/catalog_FormFieldType' description: >- Input control type. `password` masks secret values; `tags` collects a list of strings submitted as a JSON array. label: type: string description: The name to display for the input. name: type: string description: The literal input name, matching the install input property. required: type: boolean description: Whether the input must be provided to install the package. description: |- A single form input, translated from one property of the package's install input schema. catalog_FormFieldType: type: string enum: - text - password - tags description: |- Input control type for a form field. `tags` is rendered for array-of-string inputs and submitted back as a JSON array of strings. x-enum-varnames: - Text - Password - FormFieldTypeTags catalog_JsonSchema: type: object properties: type: allOf: - $ref: '#/components/schemas/catalog_JsonSchemaType' description: The JSON Schema `type` keyword. title: type: string description: Human-readable title (annotation). description: type: string description: Human-readable description (annotation). default: description: Default value (annotation). const: description: Constant allowed value. enum: type: array items: {} description: Enumerated allowed values. writeOnly: type: boolean description: Write-only hint (passwords, secrets) — never returned on read. readOnly: type: boolean description: Read-only hint — server-populated, ignored on write. format: type: string description: Format hint (e.g., "uri", "uuid", "email", "date-time"). properties: allOf: - $ref: '#/components/schemas/catalog_JsonSchemaProperties' description: Property schemas, keyed by property name. required: type: array items: type: string description: Names of required properties. additionalProperties: allOf: - $ref: '#/components/schemas/catalog_JsonSchema' description: Schema for properties not named in `properties`. items: allOf: - $ref: '#/components/schemas/catalog_JsonSchema' description: Schema for array items. minItems: type: integer maxItems: type: integer pattern: type: string minLength: type: integer maxLength: type: integer minimum: type: number maximum: type: number description: >- A subset of JSON Schema 2020-12 used to describe package input and output shapes. Supported keywords: - Structural: `type`, `properties`, `required`, `items`, `additionalProperties` - Annotations: `title`, `description`, `default`, `readOnly`, `writeOnly` - Constraints: `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`, `minItems`, `maxItems`, `enum`, `const`, `format` Intentionally unsupported (reject at release time rather than silently ignore): - Schema combinators: `allOf`, `anyOf`, `oneOf`, `not` - References: `$ref`, `$dynamicRef` - `patternProperties`, `propertyNames`, `unevaluatedProperties` - Custom vocabularies and `$vocabulary` Dialect: JSON Schema 2020-12 (implied — authors do not include `$schema`). catalog_JsonSchemaProperties: type: object additionalProperties: $ref: '#/components/schemas/catalog_JsonSchema' description: Map of property name to a JSON Schema describing that property. catalog_JsonSchemaType: type: string enum: - object - array - string - integer - number - boolean - 'null' description: The `type` keyword in JSON Schema 2020-12. catalog_Keycard.Catalog.Vocabulary.markdown: type: string format: markdown catalog_PackageInputBinding: type: object properties: schema: allOf: - $ref: '#/components/schemas/catalog_JsonSchema' description: |- JSON Schema constraining install-level inputs for this package. Must be a subset of the package kind's inputs schema. Properties listed in `required` must be provided at install creation time. bindings: type: string description: |- CEL expression assembling the flat input map from static values and install-provided values (referenced via `pkg.inputs.X`). Scope: - `pkg.inputs` — install-supplied values conforming to `schema`. description: >- Input binding for a package. `schema` constrains install-level inputs. `bindings` is a CEL expression that assembles the flat input map — static values are CEL literals, install-provided values are `pkg.inputs.X` references. Evaluated at provisioning time to produce the `entities.inputs` map for entity bindings. catalog_PaginationCursor: type: string description: An opaque cursor used for paginating through a list of results minLength: 1 maxLength: 255 x-go-type: types.PaginationCursor x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types catalog_Pagination: type: object description: Cursor-based pagination metadata returned alongside a list of results properties: before_cursor: type: string nullable: true allOf: - $ref: '#/components/schemas/catalog_PaginationCursor' after_cursor: type: string nullable: true allOf: - $ref: '#/components/schemas/catalog_PaginationCursor' total_count: type: integer description: >- Total number of items across all pages. Only present when the request includes ?expand[]=total_count. required: - before_cursor - after_cursor additionalProperties: false x-go-type: types.Pagination x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/types name: types catalog_ActionRefreshResult: type: object required: - resource_id - tool_count - truncated - changed properties: resource_id: type: string description: The resource whose actions were recorded. tool_count: type: integer description: How many tools the walk observed. truncated: type: boolean description: >- True when the walk stopped before the server ran out of pages. What was seen is still recorded, and nothing is retired, since a tool missing from a partial walk has not been shown to be gone. changed: type: boolean description: Whether recording the observation altered the resource's actions. description: What a completed walk observed. catalog_ActionRefreshStartRequest: type: object properties: return_to: type: string description: >- Where to send the user's browser once the walk is done, so a caller that leaves the round trip to this service still gets its page back. Must match a specific allowed origin, which is typically the Keycard Console URL in the catalog's deployment. Omit it and the browser stops on a page from this service. description: Where to come back to once the user has authorized the walk. catalog_ActionRefreshStartResponse: type: object oneOf: - required: - authorization_url - required: - completed - tool_count - truncated - changed properties: completed: type: boolean description: >- True when the refresh is already done, because the zone still held the user's authorization for this server and no browser leg was needed. The counts are then present and `authorization_url` is absent. tool_count: type: integer minimum: 0 description: How many tools the walk recorded, when it ran. truncated: type: boolean description: >- True when the walk reached its page limit before enumeration finished. Existing actions absent from that incomplete list are retained. changed: type: boolean description: True when observed tools were recorded in IAM. warning: type: string enum: - incomplete_list - cleanup_failed - missing_cutoff - empty_list - incomplete_refresh description: >- Present when the observation did not reconcile the complete tool list. Existing actions may remain. The response is completed and does not require browser authorization. authorization_url: type: string description: >- The URL the user's browser must visit. Present only when the zone holds no authorization for this user and this server yet. description: |- Either what a completed walk found, or where to send the user so a later refresh can answer without asking again. catalog_PackageKind: type: string description: A recognized catalog package kind. enum: - api-server - mcp-server-proxy x-enum-varnames: - PackageKindAPIServer - PackageKindMCPServerProxy catalog_QueryTerms: type: array description: | Value shape for `query[]` and `query[]` search parameters. Wire conventions: - Case-insensitive substring match (ILIKE). - Repeated parameter instances are OR-ed across terms. - Comma splitting is NOT performed; literal commas in a search term are preserved as part of the term. Examples: ?query[name]=alpha&query[name]=beta -> name ILIKE %alpha% OR name ILIKE %beta% ?query[]=alpha -> any searchable field ILIKE %alpha% Cross-field form is `query[]`; field-scoped form is `query[]`. Field names are endpoint-specific; services declare each query parameter per operation. items: type: string minLength: 1 maxLength: 255 catalog_ErrorCode: type: string enum: - validation_error - bad_request - unauthorized - forbidden - not_found - conflict - rate_limit_exceeded - internal_error - not_implemented - service_unavailable x-enum-varnames: - ValidationErrorCode - BadRequestErrorCode - UnauthorizedErrorCode - ForbiddenErrorCode - NotFoundErrorCode - ConflictErrorCode - RateLimitExceededErrorCode - InternalErrorCode - NotImplementedErrorCode - ServiceUnavailableErrorCode x-go-type: httperrors.ErrorCode x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/httperrors name: httperrors catalog_ErrorDetail: type: object properties: field: type: string description: >- valid json path for request body. Omitted when the detail is not tied to a request field (e.g. domain error codes); clients should treat absent and empty the same. message: type: string description: error message for specific error code: anyOf: - $ref: '#/components/schemas/catalog_ErrorCode' - type: string description: >- Machine-readable code. Either a common `ErrorCode` value or a service-specific domain code (snake_case) documented by the service's own API spec. Clients should match on this instead of parsing `message`. Open set; unknown codes must be tolerated. example: version_currently_bound required: - message - code additionalProperties: false x-go-type: httperrors.ErrorDetail x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/httperrors name: httperrors catalog_Error: type: object description: Represents an error that has occurred in the Keycard system. properties: status: type: integer description: HTTP Status Code code: $ref: '#/components/schemas/catalog_ErrorCode' message: type: string description: summary of the error request_id: type: string format: uuid timestamp: type: string format: date-time path: type: string format: url details: type: array items: $ref: '#/components/schemas/catalog_ErrorDetail' additionalProperties: false required: - status - code - message - request_id - timestamp - path - details x-go-type: httperrors.Error x-go-type-import: path: github.com/keycardlabs/pkg-oapi-common/golang/httperrors name: httperrors iam_PageInfo: title: Page Info description: Pagination information additionalProperties: false type: object required: - has_next_page - has_previous_page properties: has_next_page: description: Whether there are more items after the current page type: boolean has_previous_page: description: Whether there are items before the current page type: boolean start_cursor: nullable: true description: Cursor pointing to the first item in the current page type: string end_cursor: nullable: true description: Cursor pointing to the last item in the current page type: string iam_PaginationCursor: title: Pagination Cursor description: An opaque cursor used for paginating through a list of results minLength: 1 maxLength: 255 type: string iam_Pagination: title: Pagination description: Cursor-based pagination metadata additionalProperties: false type: object required: - after_cursor - before_cursor properties: after_cursor: type: string allOf: - $ref: '#/components/schemas/iam_PaginationCursor' nullable: true description: Cursor to fetch the next page of results before_cursor: type: string allOf: - $ref: '#/components/schemas/iam_PaginationCursor' nullable: true description: Cursor to fetch the previous page of results total_count: description: >- Total number of items matching the query. Only included when expand[]=total_count is requested. type: integer iam_Metadata: additionalProperties: false description: Entity metadata type: object properties: docs_url: format: uri maxLength: 2048 description: Documentation URL type: string icon_url: format: uri maxLength: 2048 description: Icon URL type: string iam_MetadataUpdate: nullable: true additionalProperties: false description: Entity metadata (set to null or {} to remove metadata) type: object properties: docs_url: format: uri maxLength: 2048 nullable: true description: Documentation URL (set to null to unset) type: string icon_url: format: uri maxLength: 2048 nullable: true description: Icon URL (set to null to unset) type: string iam_Permissions: title: Permissions description: >- Permissions granted to the authenticated principal. Only populated when expand[]=permissions query parameter is provided. Keys are resource types, values are objects mapping action names to boolean values. type: object additionalProperties: type: object additionalProperties: type: boolean example: zones: read: true update: true delete: false create: false applications: read: true list: true create: false iam_ZoneCimd: title: Zone CIMD Configuration description: Client ID Metadata Document auto-provisioning configuration type: object required: - enabled - allowed_client_ids properties: enabled: description: >- Whether CIMD auto-provisioning is enabled for unregistered URL-based clients default: false type: boolean allowed_client_ids: description: >- Allowlist for CIMD client_id URLs. Each entry is an exact URL, a wildcard origin with a single * replacing one subdomain label (e.g. https://*.example.com matches https://app.example.com but not https://a.b.example.com), or the literal * to allow any client. Only one * is permitted per entry. default: [] type: array items: type: string iam_ZoneOAuth2Protocol: title: Zone OAuth 2.0 Protocol description: OAuth 2.0 protocol configuration for a zone type: object required: - issuer - authorization_server_metadata - authorization_endpoint - token_endpoint - redirect_uri - registration_endpoint - jwks_uri - pkce_required - dcr_enabled - cimd properties: issuer: format: uri description: OAuth 2.0 issuer identifier type: string authorization_server_metadata: format: uri description: >- OAuth 2.0 Authorization Server Metadata endpoint (.well-known/oauth-authorization-server) type: string authorization_endpoint: format: uri description: OAuth 2.0 authorization endpoint type: string token_endpoint: format: uri description: OAuth 2.0 token endpoint type: string redirect_uri: format: uri description: OAuth 2.0 redirect URI for this zone type: string registration_endpoint: format: uri description: OAuth 2.0 Dynamic Client Registration endpoint type: string jwks_uri: format: uri description: JSON Web Key Set endpoint type: string pkce_required: description: Whether PKCE is required for authorization code flows type: boolean dcr_enabled: description: Whether Dynamic Client Registration is enabled type: boolean cimd: $ref: '#/components/schemas/iam_ZoneCimd' iam_ZoneOpenIDProtocol: title: Zone OpenID Connect Protocol description: OpenID Connect protocol configuration for a zone type: object required: - provider_configuration - userinfo_endpoint properties: provider_configuration: format: uri description: >- OpenID Connect Provider Configuration endpoint (.well-known/openid-configuration) type: string userinfo_endpoint: format: uri description: OpenID Connect UserInfo endpoint type: string iam_ZoneProtocol: title: Zone Protocol description: Protocol configuration for a zone type: object required: - oauth2 - openid properties: oauth2: $ref: '#/components/schemas/iam_ZoneOAuth2Protocol' openid: $ref: '#/components/schemas/iam_ZoneOpenIDProtocol' iam_ZoneOAuth2ProtocolCreate: title: Zone OAuth 2.0 Protocol Create description: OAuth 2.0 protocol configuration for zone creation type: object properties: pkce_required: description: Whether PKCE is required for authorization code flows default: true type: boolean dcr_enabled: description: Whether Dynamic Client Registration is enabled default: true type: boolean cimd: $ref: '#/components/schemas/iam_ZoneCimd' iam_ZoneProtocolCreate: title: Zone Protocol Create description: Protocol configuration for zone creation type: object properties: oauth2: $ref: '#/components/schemas/iam_ZoneOAuth2ProtocolCreate' iam_ZoneOAuth2ProtocolUpdate: title: Zone OAuth 2.0 Protocol Update description: OAuth 2.0 protocol configuration update for a zone (partial update) type: object properties: pkce_required: nullable: true description: Whether PKCE is required for authorization code flows type: boolean dcr_enabled: nullable: true description: Whether Dynamic Client Registration is enabled type: boolean cimd: $ref: '#/components/schemas/iam_ZoneCimd' iam_ZoneProtocolUpdate: title: Zone Protocol Update description: Protocol configuration update for a zone (partial update) nullable: true type: object properties: oauth2: $ref: '#/components/schemas/iam_ZoneOAuth2ProtocolUpdate' iam_EncryptionKeyAwsKmsConfig: title: AWS KMS Encryption Key Configuration description: >- AWS KMS configuration for zone encryption. When not specified, the default Keycard Cloud encryption key will be used. type: object required: - type - arn properties: type: type: string enum: - aws arn: minLength: 1 description: AWS KMS Key ARN for encrypting the zone's data type: string iam_EncryptionKeyAwsKmsConfigUpdate: title: AWS KMS Encryption Key Configuration Update description: >- AWS KMS configuration for zone encryption update (set to null to remove customer-managed key and revert to default) nullable: true type: object required: - type - arn properties: type: type: string enum: - aws arn: minLength: 1 description: AWS KMS Key ARN for encrypting the zone's data type: string iam_ProviderOAuth2Protocol: title: Provider OAuth 2.0 Protocol description: OAuth 2.0 protocol configuration nullable: true type: object required: - issuer properties: issuer: format: uri description: OIDC issuer URL used for discovery and token validation. type: string authorization_endpoint: format: uri nullable: true type: string token_endpoint: format: uri nullable: true type: string registration_endpoint: format: uri nullable: true type: string jwks_uri: format: uri nullable: true type: string code_challenge_methods_supported: nullable: true type: array items: type: string scopes_supported: nullable: true type: array items: type: string authorization_resource_enabled: nullable: true description: Whether to include the resource parameter in authorization requests. type: boolean authorization_resource_parameter: nullable: true description: >- The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. type: string scope_parameter: nullable: true description: >- The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope". type: string scope_separator: nullable: true description: >- The separator character for scope values. Defaults to " " (space). Slack v2 uses ",". type: string token_response_access_token_pointer: nullable: true description: >- Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token". type: string authorization_parameters: nullable: true description: >- Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline). type: object additionalProperties: type: string iam_ProviderOpenIDProtocol: title: Provider OpenID Connect Protocol description: OpenID Connect protocol configuration nullable: true type: object properties: userinfo_endpoint: format: uri nullable: true type: string user_identifier_claim: nullable: true description: >- Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. When not set, the user's Keycard ID is used. type: string scopes: nullable: true description: >- Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). type: array items: type: string single_logout_enabled: nullable: true description: >- When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. type: boolean iam_ProviderProtocol: title: Provider Protocol description: Protocol-specific configuration nullable: true type: object properties: oauth2: $ref: '#/components/schemas/iam_ProviderOAuth2Protocol' openid: $ref: '#/components/schemas/iam_ProviderOpenIDProtocol' iam_ProviderOAuth2ProtocolCreate: title: Provider OAuth 2.0 Protocol Create description: OAuth 2.0 protocol configuration for provider creation type: object properties: issuer: format: uri description: >- OIDC issuer URL for discovery and token validation. When omitted, the provider identifier is used as the issuer. New clients should always set this explicitly. type: string authorization_endpoint: format: uri type: string token_endpoint: format: uri type: string registration_endpoint: format: uri type: string jwks_uri: format: uri type: string code_challenge_methods_supported: type: array items: type: string scopes_supported: type: array items: type: string authorization_resource_enabled: description: Whether to include the resource parameter in authorization requests. type: boolean authorization_resource_parameter: description: >- The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. type: string scope_parameter: description: >- The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope". type: string scope_separator: description: >- The separator character for scope values. Defaults to " " (space). Slack v2 uses ",". type: string token_response_access_token_pointer: description: >- Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token". type: string authorization_parameters: description: >- Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline). type: object additionalProperties: type: string iam_ProviderOpenIDProtocolCreate: title: Provider OpenID Connect Protocol Create description: OpenID Connect protocol configuration for provider creation type: object properties: userinfo_endpoint: format: uri type: string user_identifier_claim: description: >- Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. When not set, the user's Keycard ID is used. type: string scopes: description: >- Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). type: array items: type: string single_logout_enabled: description: >- When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. type: boolean iam_ProviderProtocolCreate: title: Provider Protocol Create description: Protocol-specific configuration for provider creation type: object properties: oauth2: $ref: '#/components/schemas/iam_ProviderOAuth2ProtocolCreate' openid: $ref: '#/components/schemas/iam_ProviderOpenIDProtocolCreate' iam_ProviderOAuth2ProtocolUpdate: title: Provider OAuth 2.0 Protocol Update description: >- OAuth 2.0 protocol configuration. Set to null to remove all OAuth2 config. nullable: true type: object properties: issuer: format: uri description: >- OIDC issuer URL for discovery and token validation. Cannot be set to null. type: string authorization_endpoint: format: uri nullable: true type: string token_endpoint: format: uri nullable: true type: string registration_endpoint: format: uri nullable: true type: string jwks_uri: format: uri nullable: true type: string code_challenge_methods_supported: nullable: true type: array items: type: string scopes_supported: nullable: true type: array items: type: string authorization_resource_enabled: nullable: true description: >- Whether to include the resource parameter in authorization requests. Set to null to unset. type: boolean authorization_resource_parameter: nullable: true description: >- The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. Set to null to unset. type: string scope_parameter: nullable: true description: >- The query parameter name for scopes in authorization requests. Defaults to "scope". Set to null to unset. type: string scope_separator: nullable: true description: >- The separator character for scope values. Defaults to " " (space). Set to null to unset. type: string token_response_access_token_pointer: nullable: true description: >- Dot-separated path to the access token in the token response body. Defaults to "access_token". Set to null to unset. type: string authorization_parameters: nullable: true description: >- Custom query parameters appended to authorization redirect URLs. Set to null to unset. type: object additionalProperties: type: string iam_ProviderOpenIDProtocolUpdate: title: Provider OpenID Connect Protocol Update description: >- OpenID Connect protocol configuration. Set to null to remove all OpenID config. nullable: true type: object properties: userinfo_endpoint: format: uri nullable: true type: string user_identifier_claim: nullable: true description: >- Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. Set to null to revert to default. Changing this value does not affect existing users. type: string scopes: nullable: true description: >- Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). Set to null to clear. type: array items: type: string single_logout_enabled: nullable: true description: >- When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. type: boolean iam_ProviderProtocolUpdate: title: Provider Protocol Update description: Protocol-specific configuration. Set to null to remove all protocols. nullable: true type: object properties: oauth2: $ref: '#/components/schemas/iam_ProviderOAuth2ProtocolUpdate' openid: $ref: '#/components/schemas/iam_ProviderOpenIDProtocolUpdate' iam_ApplicationOAuth2Protocol: title: Application OAuth 2.0 Protocol description: OAuth 2.0 protocol configuration nullable: true additionalProperties: false type: object properties: redirect_uris: nullable: true description: OAuth 2.0 redirect URIs for this application x-audit: true type: array items: format: uri type: string post_logout_redirect_uris: nullable: true description: OAuth 2.0 post-logout redirect URIs for this application x-audit: true type: array items: format: uri type: string iam_ApplicationProtocol: title: Application Protocol description: Protocol-specific configuration nullable: true additionalProperties: false type: object properties: oauth2: $ref: '#/components/schemas/iam_ApplicationOAuth2Protocol' iam_ApplicationOAuth2ProtocolCreate: title: Application OAuth 2.0 Protocol Create description: OAuth 2.0 protocol configuration for application creation additionalProperties: false type: object properties: redirect_uris: description: OAuth 2.0 redirect URIs for this application type: array items: format: uri type: string post_logout_redirect_uris: description: OAuth 2.0 post-logout redirect URIs for this application type: array items: format: uri type: string iam_ApplicationProtocolCreate: title: Application Protocol Create description: Protocol-specific configuration for application creation additionalProperties: false type: object properties: oauth2: $ref: '#/components/schemas/iam_ApplicationOAuth2ProtocolCreate' iam_ApplicationOAuth2ProtocolUpdate: title: Application OAuth 2.0 Protocol Update description: OAuth 2.0 protocol configuration for application update nullable: true additionalProperties: false type: object properties: redirect_uris: nullable: true description: >- OAuth 2.0 redirect URIs for this application (set to null or [] to unset) type: array items: format: uri type: string post_logout_redirect_uris: nullable: true description: >- OAuth 2.0 post-logout redirect URIs for this application (set to null or [] to unset) type: array items: format: uri type: string iam_ApplicationProtocolUpdate: title: Application Protocol Update description: Protocol-specific configuration for application update nullable: true additionalProperties: false type: object properties: oauth2: $ref: '#/components/schemas/iam_ApplicationOAuth2ProtocolUpdate' iam_ApplicationCredentialCreateToken: title: Application Credential Create Token description: Schema for creating a token application credential type: object required: - application_id - type - provider_id properties: application_id: description: ID of the application this credential belongs to type: string type: type: string enum: - token provider_id: description: ID of the provider issuing tokens this credential verifies type: string subject: description: >- Subject identifier for the token. When omitted, any token from the provider is accepted without checking application-specific claims. type: string iam_ApplicationCredentialCreatePassword: title: Application Credential Create Password description: Schema for creating a password application credential type: object required: - application_id - type properties: application_id: description: ID of the application this credential belongs to type: string type: type: string enum: - password identifier: description: >- Username for password credential, also used as OAuth 2.0 client ID (auto-generated if not provided) type: string iam_ApplicationCredentialCreatePublicKey: title: Application Credential Create Public Key description: Schema for creating a public key application credential type: object required: - application_id - type - jwks_uri properties: application_id: description: ID of the application this credential belongs to type: string type: type: string enum: - public-key jwks_uri: format: uri description: JWKS URI to retrieve public keys from type: string identifier: description: >- Client ID for public key credential, also used as OAuth 2.0 client ID (auto-generated if not provided) type: string iam_ApplicationCredentialCreateUrl: title: Application Credential Create URL description: Schema for creating a URL application credential type: object required: - application_id - type - identifier properties: application_id: description: ID of the application this credential belongs to type: string type: type: string enum: - url identifier: format: uri description: URL of the credential (must be a valid URL) type: string iam_ApplicationCredentialCreatePublic: title: Application Credential Create Public description: Schema for creating a public application credential type: object required: - application_id - type properties: application_id: description: ID of the application this credential belongs to type: string type: type: string enum: - public identifier: description: >- Identifier for public credential, also used as OAuth 2.0 client ID (auto-generated if not provided) type: string iam_Error: title: Error description: Error response type: object required: - message - code - status properties: message: type: string code: type: string status: type: number iam_Provider: title: Provider description: >- A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. type: object required: - id - organization_id - zone_id - slug - name - identifier - owner_type - created_at - updated_at properties: id: description: Unique identifier of the provider type: string organization_id: description: Organization that owns this provider type: string zone_id: description: Zone this provider belongs to type: string slug: pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ minLength: 1 maxLength: 63 description: URL-safe identifier, unique within the zone type: string name: minLength: 1 maxLength: 255 description: Human-readable name x-audit: true type: string description: maxLength: 2048 nullable: true description: Human-readable description x-audit: true type: string identifier: minLength: 1 maxLength: 2048 description: User specified identifier, unique within the zone x-audit: true type: string type: type: string enum: - external - keycard-vault - keycard-sts client_id: nullable: true description: OAuth 2.0 client identifier type: string client_secret_set: description: Indicates whether a client secret is configured type: boolean protocols: nullable: true description: Protocol-specific configuration type: object properties: oauth2: $ref: '#/components/schemas/iam_ProviderOAuth2Protocol' openid: $ref: '#/components/schemas/iam_ProviderOpenIDProtocol' metadata: nullable: true description: Provider metadata type: object properties: icon_url: format: uri maxLength: 2048 description: Icon URL type: string owner_type: type: string enum: - platform - customer description: >- Who owns this provider. Platform-owned providers cannot be modified via API. created_at: format: date-time description: Entity creation timestamp type: string updated_at: format: date-time description: Entity update timestamp type: string iam_ProviderCreate: title: Provider Create description: Schema for creating a new provider type: object required: - name - identifier properties: name: minLength: 1 maxLength: 255 format: safe-text description: >- Human-readable name. Must not contain HTML tags (e.g. `