Skip to main content
POST
http://localhost:3000
/
subjects
/
batch
curl -X POST 'https://api.example.com/subjects/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "subject_user_jane",
      "subjectType": "user",
      "externalId": "user-jane-doe",
      "displayName": "Jane Doe",
      "meta": {"email": "jane@acme.com"}
    },
    {
      "subjectType": "agent",
      "externalId": "coding-assistant-v1",
      "displayName": "Coding Assistant",
      "meta": {"model": "claude-3"}
    }
  ]'

[
  {
    "id": "subject_user_jane",
    "subjectType": "user",
    "externalId": "user-jane-doe",
    "displayName": "Jane Doe",
    "meta": {"email": "jane@acme.com"}
  },
  {
    "id": "subject_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "subjectType": "agent",
    "externalId": "coding-assistant-v1",
    "displayName": "Coding Assistant",
    "meta": {"model": "claude-3"}
  }
]

​
Overview

Batch creation allows you to create multiple subjects in a single API call. This is more efficient than making individual requests and supports in-batch ID references. Each subject can optionally include inline memberships with role assignments.
ID Format: All IDs use a namespaced UUIDv7 format: subject_{uuidv7}. You can optionally provide your own IDs for in-batch references.

​
Request Body

Array of subject objects:
​
[].id
string
Optional client-provided ID. Useful for referencing within the same batch. Must be unique.
​
[].subjectType
string
required
Subject type. One of: user, api_key, service, agent
​
[].externalId
string
required
External identifier for the subject
​
[].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 an array of created subject objects. If memberships were provided, each subject includes the created memberships with their role assignments. 
curl -X POST 'https://api.example.com/subjects/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "subject_user_jane",
      "subjectType": "user",
      "externalId": "user-jane-doe",
      "displayName": "Jane Doe",
      "meta": {"email": "jane@acme.com"}
    },
    {
      "subjectType": "agent",
      "externalId": "coding-assistant-v1",
      "displayName": "Coding Assistant",
      "meta": {"model": "claude-3"}
    }
  ]'

[
  {
    "id": "subject_user_jane",
    "subjectType": "user",
    "externalId": "user-jane-doe",
    "displayName": "Jane Doe",
    "meta": {"email": "jane@acme.com"}
  },
  {
    "id": "subject_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "subjectType": "agent",
    "externalId": "coding-assistant-v1",
    "displayName": "Coding Assistant",
    "meta": {"model": "claude-3"}
  }
]