Skip to main content
POST
Give a role
Gives one role to a person, an agent, an API key or an External App (actorKind and actorId, as listGrants names them), at an org unit (orgUnitId) or the platform scope, as the Forge Console’s Access page gives it. The calling credential is the giver: a platform key or an External App gives as itself, a Personal key as its owner. It may give only a role whose every permission it holds where the grant is, counted from its own grants at the scopes covering that place and narrowed by its scopes; never to itself, never a compatibility role, and a per-company role only at an org unit. A refusal is 403 forbidden with error.reason: "role_giving_refused" and each reason in error.refusals, and nothing changes. The grant records the credential as its giver; the audit trail records the change, the credential and reason, which no read returns. Giving a role already held there changes nothing; giving a revoked one again re-enables it. With an Idempotency-Key, a retry within 24 hours returns the recorded result while you still hold grants:manage there. See Roles and grants.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without changing anything again.

Required string length: 1 - 255

Path Parameters

holderId
string
required

The holder's id: a person's id, an agent definition's id, an API key's id or an External App's id, as listGrants returns them.

Minimum string length: 1

Body

application/json

Give one role to one holder, at an org unit or the platform scope.

actorKind
enum<string>
required

The holder's kind: a person, an agent, an API key or an External App.

Available options:
person,
agent,
api_key,
external_app
roleKey
string
required

The role, by key (listRoleDefinitions).

Minimum string length: 1
orgUnitId
string

The org unit the grant is at. Absent: the platform scope.

Minimum string length: 1
reason
string

Why, in your words; recorded on the audit event, never returned by a read (at most 280 characters).

Maximum string length: 280
expiresAt
integer

When the grant stops counting, in epoch milliseconds. Absent: it does not expire.

Response

Give a role

data
object
required

The grant: created for a new grant, restored when a revoked or expired grant was re-enabled; both false when the holder already held the role there. orgUnitId is where it is (null: the platform scope).

meta
object
required