KEkeycardai
Zone Roles

Assign role to application

Changed on

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.

post/zones/{zoneId}/applications/{applicationId}/roles

Request

  • Base URL
    https://docs.keycard.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://docs.keycard.ai/zones/{zoneId}/applications/{applicationId}/roles
  • Auth
    • HTTP bearer
    • or OAuth 2
      Client credentials
      Token URL: /service-account-token

Path parameters

zoneIdstring required

Zone ID

applicationIdstring required

Application ID

Request body

role_idstring

ID of the role to assign. Provide exactly one of role_id or role_identifier; owner_type must be omitted when role_id is used.

role_identifierstring

Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.

owner_type'platform' | 'customer'

Owner type of the role to assign. Required with role_identifier (an identifier is unique only per owner type); must be omitted with role_id.

scope_typestring

The kind of resource to scope the grant to (e.g. zone). Provide together with scope_id, or omit both for an unscoped assignment (applies to the owning zone itself). Only platform roles on the org zone may carry a scope.

scope_idstring

The ID of the resource to scope the grant to. Provide together with scope_type, or omit both for an unscoped assignment. When scope_type is zone, this must reference a different zone in the same organization.

Response

Represents a role assigned to a principal within a zone

idstring required

Unique identifier of the role assignment

zone_idstring required

Zone this assignment belongs to

principal_typestring required

The kind of principal the role is assigned to: user, application, or group. A role assigned to a group is inherited by that group's members.

principal_idstring required

ID of the principal the role is assigned to (a user, application, or group ID).

role_idstring required

ID of the assigned role

role_identifierstring required

Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text.

role_owner_type'platform' | 'customer' required

Owner type of the assigned role. Disambiguates roles that share an identifier across owner types.

scope_typestring nullable

The kind of resource this grant is scoped to (e.g. zone). Null when the assignment is unscoped (applies to the owning zone itself).

scope_idstring nullable

The ID of the scoped resource. Null when the assignment is unscoped.

created_atstring date-time required

Entity creation timestamp

updated_atstring date-time required

Entity update timestamp

Changes