Skip to content
Kindgi

Add a person

View as Markdown
POST
/v1/identity/users
curl --request POST \
  --url https://example.com/v1/identity/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "displayName": "example", "primaryEmail": "example", "sendInvite": true }'

Adds a person to the tenant as a tenant member, written before it answers: they can read the tenant’s settings (providers, policies, adapters, signing keys, deployments), not its projects. Give them a role to work (project or team membership, or tenant admin), then mint their first API key at POST /v1/tokens with for. A person added with an email is invited (invite): they sign in within 7 days, or a tenant admin renews it (POST /v1/identity/users/{userId}/invite); the invitation is emailed where the deployment sends email, and inviteEmail says whether it was. Tenant admins only. Mounted when the identity directory can add people.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
displayName
required
string
>= 1 characters <= 200 characters
primaryEmail

Unique among the tenant’s people.

string
sendInvite

Email them the invitation (default true). false still invites them, for an admin who tells them another way. A person without an email isn’t invited.

boolean
Examplegenerated
{
  "displayName": "example",
  "primaryEmail": "example",
  "sendInvite": true
}

Responses

Section titled “Responses”

201

Section titled “201”

The new person, and whether their invitation was emailed.

Media typeapplication/json

The person just added, and whether their invitation was emailed (inviteEmail: absent from a runtime that sends no invitations).

object
userId
required
string
tenantId
required
string format: uuid
primaryEmail
string
displayName
string
createdAt
required
string format: date-time
lastActiveAt
string format: date-time
unregisteredAt

When they were removed from the tenant (POST /v1/identity/users/{userId}/unregister); absent while they are here.

string format: date-time
invite

Their invitation, while they haven’t signed in: absent once they have, for people added without an email, and for people added before invitations (from 0.1.9).

object
state
required
string
Allowed values: pending expired
expiresAt
required
string format: date-time
sentAt

When it was last emailed; absent when it never was.

string format: date-time
firstSignedInAt

Their first sign-in that made a session. Absent before it, and for people who last signed in before it was kept (from 0.1.9).

string format: date-time
metadata
object
key
additional properties
any
inviteEmail

Whether the invitation was emailed, and why not: no-email (the person has no email, so isn’t invited), not-requested (sendInvite: false), not-configured (the deployment sends no email), send-failed (the mail server refused it or didn’t answer), capped (the workspace, or the whole deployment, has sent as many invitation emails as it may in 24 hours). An invitation not emailed is still open: tell them yourself.

object
sent
required
boolean
reason
string
Allowed values: no-email not-requested not-configured send-failed capped
Example
{
  "invite": {
    "state": "pending"
  },
  "inviteEmail": {
    "reason": "no-email"
  }
}

400

Section titled “400”

Malformed request body.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

Not a tenant admin.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Another person of the tenant has the email (identity-user-email-taken), or an idempotency conflict.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also