Skip to main content
POST
/
subjects
curl -X POST 'https://api.example.com/subjects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "subjectType": "user",
    "externalId": "user-456",
    "displayName": "John Doe",
    "meta": {"email": "john@example.com"}
  }'

{
  "id": "subject_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "subjectType": "user",
  "externalId": "user-456",
  "displayName": "John Doe",
  "meta": {"email": "john@example.com"}
}

​
Overview

Create a new subject (user, agent, API key, or service). Optionally add the subject to scopes and assign roles in a single request using inline memberships.
ID Format: All IDs use a namespaced UUIDv7 format: subject_{uuidv7}. You can optionally provide your own ID.

​
Request Body

​
id
string
Optional client-provided ID. Format: subject_{uuidv7}
​
subjectType
string
required
Subject type. One of: user, api_key, service, agent
​
externalId
string
required
External identifier for the subject (e.g., user ID from your auth system)
​
displayName
string
Display name for the subject
​
meta
object
Optional metadata to associate with the subject
​
memberships
array
Optional inline memberships with role assignments. Creates memberships and role assignments in a single request.
​
memberships[].scopeId
string
required
ID of the scope to add the subject to
​
memberships[].roleIds
array
Optional array of role IDs to assign to the membership

​
Response

Returns the created subject object. If memberships were provided, includes the created memberships with their role assignments. 
curl -X POST 'https://api.example.com/subjects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "subjectType": "user",
    "externalId": "user-456",
    "displayName": "John Doe",
    "meta": {"email": "john@example.com"}
  }'

{
  "id": "subject_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "subjectType": "user",
  "externalId": "user-456",
  "displayName": "John Doe",
  "meta": {"email": "john@example.com"}
}