Skip to main content
POST
/
scopes
curl -X POST 'https://api.example.com/scopes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Engineering Team",
    "typeId": "type_team",
    "externalId": "team-eng",
    "parentScopeId": "scope_org",
    "memberships": [
      {"subjectId": "subject_jane", "roleIds": ["role_admin"]},
      {"subjectId": "subject_bob", "roleIds": ["role_member"]}
    ]
  }'

{
  "id": "scope_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "name": "Engineering Team",
  "typeId": "type_team",
  "externalId": "team-eng"
}

​
Request Body

​
id
string
Optional client-provided ID. Format: scope_{uuidv7}
​
typeId
string
required
The scope type ID
​
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. If provided, automatically creates a scope hierarchy edge.
​
memberships
array
Optional array of inline memberships to create with the scope. Each membership has:
  • subjectId (required): The subject to add to this scope
  • roleIds (optional): Array of role IDs to assign to the membership

​
Response

Returns the created scope object.
You can create a scope with its parent relationship and initial memberships in a single request using parentScopeId and memberships.
curl -X POST 'https://api.example.com/scopes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Engineering Team",
    "typeId": "type_team",
    "externalId": "team-eng",
    "parentScopeId": "scope_org",
    "memberships": [
      {"subjectId": "subject_jane", "roleIds": ["role_admin"]},
      {"subjectId": "subject_bob", "roleIds": ["role_member"]}
    ]
  }'

{
  "id": "scope_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "name": "Engineering Team",
  "typeId": "type_team",
  "externalId": "team-eng"
}

​
Examples

​
Basic Scope

curl -X POST 'https://api.example.com/scopes' \
  -d '{
    "name": "Engineering",
    "typeId": "type_department"
  }'

​
Scope with Parent

curl -X POST 'https://api.example.com/scopes' \
  -d '{
    "name": "Backend Team",
    "typeId": "type_team",
    "parentScopeId": "scope_engineering"
  }'

​
Scope with Memberships and Roles

curl -X POST 'https://api.example.com/scopes' \
  -d '{
    "name": "Project Alpha",
    "typeId": "type_project",
    "parentScopeId": "scope_team",
    "memberships": [
      {"subjectId": "subject_jane", "roleIds": ["role_admin", "role_developer"]},
      {"subjectId": "subject_bob", "roleIds": ["role_developer"]},
      {"subjectId": "subject_agent", "roleIds": ["role_viewer"]}
    ]
  }'