Create Scope

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"
}

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

string

Optional client-provided ID. Format: scope_{uuidv7}

string

required

The scope type ID

string

Display name for the scope

string

External identifier for the scope

object

Optional metadata to associate with the scope

string

Optional parent scope ID. If provided, automatically creates a scope hierarchy edge.

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"]}
    ]
  }'

Overview

Subjects

Memberships

Roles

Role Assignments

Permissions

Role Permissions

Scopes

Scope Types

Scope Hierarchy

Scope Type Hierarchy

Scope Overrides

Resource Types

Resources

Resource Scope Links

Resource Collections

Resource Policies

Tag Groups

Tags

Tag Bindings

Tag Assignments

Tenants

Workspaces

Projects

Environments

Users

API Keys

Request Body

Response

Examples

Basic Scope

Scope with Parent

Scope with Memberships and Roles

​Request Body

​Response

​Examples

​Basic Scope

​Scope with Parent

​Scope with Memberships and Roles

Request Body

Response

Examples

Basic Scope

Scope with Parent

Scope with Memberships and Roles