Skip to main content
POST
/
scopes
/
batch
curl -X POST 'https://api.example.com/scopes/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "scope_engineering",
      "typeId": "type_department",
      "name": "Engineering",
      "parentScopeId": "scope_env_production",
      "memberships": [
        {"subjectId": "subject_jane", "roleIds": ["role_admin"]}
      ]
    },
    {
      "id": "scope_backend",
      "typeId": "type_team",
      "name": "Backend Team",
      "parentScopeId": "scope_engineering",
      "memberships": [
        {"subjectId": "subject_jane", "roleIds": ["role_lead"]},
        {"subjectId": "subject_bob", "roleIds": ["role_developer"]},
        {"subjectId": "subject_alice", "roleIds": ["role_developer"]}
      ]
    },
    {
      "id": "scope_frontend",
      "typeId": "type_team",
      "name": "Frontend Team",
      "parentScopeId": "scope_engineering",
      "memberships": [
        {"subjectId": "subject_charlie", "roleIds": ["role_lead"]}
      ]
    }
  ]'

[
  {
    "id": "scope_engineering",
    "typeId": "type_department",
    "name": "Engineering"
  },
  {
    "id": "scope_backend",
    "typeId": "type_team",
    "name": "Backend Team"
  },
  {
    "id": "scope_frontend",
    "typeId": "type_team",
    "name": "Frontend Team"
  }
]

​
Overview

Batch creation allows you to create multiple scopes in a single API call. You can provide client IDs for in-batch references, set up parent relationships, and add memberships with role assignments.
ID Format: All IDs use a namespaced UUIDv7 format: scope_{uuidv7}. You can optionally provide your own IDs for in-batch references.

​
Request Body

Array of scope objects:
​
[].id
string
Optional client-provided ID. Useful for referencing within the same batch.
​
[].typeId
string
required
ID of the scope type
​
[].name
string
Display name for the scope
​
[].externalId
string
External identifier for the scope
​
[].meta
object
Optional metadata to associate with the scope
​
[].parentScopeId
string
Optional parent scope ID. Automatically creates a scope hierarchy edge.
​
[].memberships
array
Optional array of inline memberships. Each membership has:
  • subjectId (required): The subject to add to this scope
  • roleIds (optional): Array of role IDs to assign

​
Response

Returns an array of created scope objects.
Each scope can include parentScopeId and memberships to set up the complete structure in one request.
curl -X POST 'https://api.example.com/scopes/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "scope_engineering",
      "typeId": "type_department",
      "name": "Engineering",
      "parentScopeId": "scope_env_production",
      "memberships": [
        {"subjectId": "subject_jane", "roleIds": ["role_admin"]}
      ]
    },
    {
      "id": "scope_backend",
      "typeId": "type_team",
      "name": "Backend Team",
      "parentScopeId": "scope_engineering",
      "memberships": [
        {"subjectId": "subject_jane", "roleIds": ["role_lead"]},
        {"subjectId": "subject_bob", "roleIds": ["role_developer"]},
        {"subjectId": "subject_alice", "roleIds": ["role_developer"]}
      ]
    },
    {
      "id": "scope_frontend",
      "typeId": "type_team",
      "name": "Frontend Team",
      "parentScopeId": "scope_engineering",
      "memberships": [
        {"subjectId": "subject_charlie", "roleIds": ["role_lead"]}
      ]
    }
  ]'

[
  {
    "id": "scope_engineering",
    "typeId": "type_department",
    "name": "Engineering"
  },
  {
    "id": "scope_backend",
    "typeId": "type_team",
    "name": "Backend Team"
  },
  {
    "id": "scope_frontend",
    "typeId": "type_team",
    "name": "Frontend Team"
  }
]

​
Examples

​
Basic Batch

curl -X POST 'https://api.example.com/scopes/batch' \
  -d '[
    {"typeId": "type_team", "name": "Team A"},
    {"typeId": "type_team", "name": "Team B"},
    {"typeId": "type_team", "name": "Team C"}
  ]'

​
With In-Batch Parent References

Use client-provided IDs to reference scopes within the same batch: 
curl -X POST 'https://api.example.com/scopes/batch' \
  -d '[
    {
      "id": "scope_dept",
      "typeId": "type_department",
      "name": "Engineering"
    },
    {
      "typeId": "type_team",
      "name": "Backend",
      "parentScopeId": "scope_dept"
    },
    {
      "typeId": "type_team",
      "name": "Frontend",
      "parentScopeId": "scope_dept"
    }
  ]'