Auth API reference

Auth API · Consumer-Tenants

post/{app_slug}/v1/tenants/{tenant_id}/membersAuth

Add a member to a tenant. Pass `accountId` for an existing user, or `email` (+ optional `display_name`/`username`) to auto-create the account inline. PAK must hold auth.tenant.members.add.

Path parameters

app_slug*string

Slug of the app.

tenant_id*string

Id of the tenant.

Headers

Idempotency-Keystring

Retry safety: a repeat with the same key and body replays the first response instead of creating a membership (or an account) again. Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.

Request body

account_idstring

UUID of an existing EndUser account in this app. Use this OR `email`.

emailstring

Email address; auto-creates an account when not yet known to this app. Use this OR `accountId`.

display_namestring

Display name for the auto-created account.

usernamestring

Username for the auto-created account; derived from the email when omitted.

Example: "john_doe"

role_name*string

Role name from this app's `role` table; case-insensitive lookup.

Example: "member"

Response · 201 Membership row.

membership*object
id*string

Unique identifier of the tenant membership.

tenant_id*string

The tenant the tenant membership belongs to.

account_id*string

The end user (account) the tenant membership belongs to.

role_id*string

Id of the role.

role_name*string

Name of the role.

joined_at*string · date-time

When the member joined the tenant (ISO 8601).

invited_by*string

The account that created the invite, or `null` when an API key did.

account_id*string

The end user (account) the add member belongs to.

created_account*boolean

True when a new account was created inline (only possible via the email branch).

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/tenants/{tenant_id}/members
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "account_id": "string",
  "email": "string",
  "display_name": "string",
  "username": "john_doe",
  "role_name": "member"
}

Response

{
  "membership": {
    "id": "string",
    "tenant_id": "string",
    "account_id": "string",
    "role_id": "string",
    "role_name": "string",
    "joined_at": "2026-01-01T00:00:00.000Z",
    "invited_by": "string"
  },
  "account_id": "string",
  "created_account": false
}