Roles

Assign role to user

client.zones.users.roles.assign(, , ?): RoleAssignment { id, created_at, principal_id, 8 more }

POST/zones/{zoneId}/users/{userId}/roles

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.

ParametersExpand Collapse

userID: string

params: RoleAssignParams { zoneId, owner_type, role_id, 3 more }

zoneId: string

Path param: Zone ID

owner_type?: "platform" | "customer"

Body param: 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.

Accepts one of the following:

"platform"

"customer"

role_id?: string

Body param: 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

Body param: 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.

minLength1

maxLength255

scope_id?: string

Body param: 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.

minLength1

scope_type?: string

Body param: 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.

minLength1

ReturnsExpand Collapse

RoleAssignment { id, created_at, principal_id, 8 more }

Represents a role assigned to a principal within a zone

id: string

Unique identifier of the role assignment

created_at: string

Entity creation timestamp

formatdate-time

principal_id: string

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

principal_type: string

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.

role_id: string

ID of the assigned role

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.

minLength1

maxLength255

role_owner_type: "platform" | "customer"

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

Accepts one of the following:

"platform"

"customer"

updated_at: string

Entity update timestamp

formatdate-time

zone_id: string

Zone this assignment belongs to

scope_id?: string | null

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

scope_type?: string | null

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

Assign role to user

import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI({
  apiKey: process.env['KEYCARD_API_API_KEY'], // This is the default and can be omitted
});

const roleAssignment = await client.zones.users.roles.assign('userId', { zoneId: 'zoneId' });

console.log(roleAssignment.id);

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "principal_id": "principal_id",
  "principal_type": "principal_type",
  "role_id": "role_id",
  "role_identifier": "role_identifier",
  "role_owner_type": "platform",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "zone_id": "zone_id",
  "scope_id": "scope_id",
  "scope_type": "scope_type"
}

Returns Examples

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "principal_id": "principal_id",
  "principal_type": "principal_type",
  "role_id": "role_id",
  "role_identifier": "role_identifier",
  "role_owner_type": "platform",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "zone_id": "zone_id",
  "scope_id": "scope_id",
  "scope_type": "scope_type"
}