Skip to main content
POST
Invite a user
Invites one person by email, as the Forge Console’s Members page invites them. Forge finds or creates the person and their seat, then gives them Builder and Auditor at the org unit named (orgUnitId), or at the platform scope when none is named. Your role grants, narrowed by your credential’s scopes, must hold grants:manage at the platform scope, as the Console’s Members page requires; a grant at an org unit does not count. Each role is then given exactly as giveRole gives it, with the calling credential as the giver and the same giving limit where the roles land, except that a re-invite never re-enables a grant an admin revoked. A refusal is 403 forbidden with error.reason: "role_giving_refused" and each reason in error.refusals, and it leaves no person, seat or role behind. status is already_exists when the person already held every invited role there. The audit trail records the invitation and each role given, naming the credential. A position cannot be assigned here; use the Console. With an Idempotency-Key, a retry within 24 hours returns the recorded result while you still hold grants:manage at the platform scope. 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

Body

application/json

Invite one person by email, at an org unit or the platform scope.

email
string<email>
required

The person's email address.

name
string

The person's display name. Absent: the email address.

Minimum string length: 1
orgUnitId
string

The org unit the invited roles are given at. Absent: the platform scope, which needs a giver who holds every invited permission there.

Minimum string length: 1

Response

Invite a user

data
object
required

The invited person's seat (workerId) and id (userId). status is created when a role was given, already_exists when the person already held every invited role there (a revoked one stays revoked). orgUnitId is where the roles are (null: the platform scope).

meta
object
required