---
title: "Assign role to application"
method: POST
path: "/zones/{zoneId}/applications/{applicationId}/roles"
tags: ["Zone Roles"]
---

# Assign role to application

`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: one of:
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `/service-account-token`

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.

## Path parameters

- `zoneId` string, required
- `applicationId` string, required

## Request body

- IamRoleAssignmentCreate: Schema for assigning a role to a principal. 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; owner_type must be omitted when role_id is used.
  - `role_id` string: 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_identifier` string: 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_type` string: 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_id` string: 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 `201`

Represents a role assigned to a principal within a zone

- IamRoleAssignment: Represents a role assigned to a principal within a zone
  - `id` string, required: Unique identifier of the role assignment
  - `zone_id` string, required: Zone this assignment belongs to
  - `principal_type` string, 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_id` string, required: ID of the principal the role is assigned to (a user, application, or group ID).
  - `role_id` string, required: ID of the assigned role
  - `role_identifier` string, 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_type` string, 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_id` string, nullable: The ID of the scoped resource. Null when the assignment is unscoped.
  - `created_at` string, date-time, required: Entity creation timestamp
  - `updated_at` string, date-time, required: Entity update timestamp

## Other responses

- `400`: Error response
- `404`: Error response
- `default`: Error response

## Changes

- **2026-08-26** `d65d51379d93`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/:zoneId/applications/:applicationId/roles/post.md)

---

[API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)