Roles

Overview

The Roles API lists the roles you can assign to accounts and groups. Role definitions are built into Material and can't be created or changed. This catalog exists so you can discover the assignable role IDs on your instance without hardcoding them.

• List Roles (GET /api/v1/roles): the assignable roles on your instance, with each one's ID, display name, description, and scope

Role assignments are managed through the account and group update endpoints, using the roles field of Update Account and Update Group. For what each role can do, see Role Descriptions.

Scope is part of the role ID

Each ID names a role and the scope it applies at, mirroring the role list under Edit Roles (Explorer > Accounts). The flavor field reports which of the three it is:

• Tenant-scoped IDs (flavor: "tenant"), such as analyst, tenant_admin, and content_admin, require tenants when assigned.
• Global IDs (flavor: "global"), such as super_admin and global_analyst, apply to every tenant and reject tenants.
• Individual IDs (flavor: "individual"), currently just tenant_enroller, grant no tenant access and take no tenants.

So the ID alone tells you how to construct a valid assignment, with no catalog lookup needed. Instances that disable global roles omit the global IDs from this catalog entirely and reject them on assignment. This response contains no tenant IDs, which appear only in assignment payloads.

Assigning and removing

roles takes assign and remove blocks, and only the roles you name are touched. It isn't a full-set replacement, so a tenant-scoped token can't accidentally clear assignments it can't see. Assigning a tenant-scoped role the account or group already holds replaces its tenant list, removing a role it doesn't hold does nothing, and naming the same ID in both blocks returns a 400.

Removal applies at every scope the role is held, so to narrow a tenant-scoped role rather than drop it, re-assign it with a shorter tenants list instead of removing it.

Roles read back on the account and group resources carry a source: direct (assigned on that account), group (inherited from the group named in groupId, and changeable only on that group), or tenant (granted to everyone in the tenant). A role reported with tenants: "all" was granted across every tenant, which you can read here but can't assign through this API.

Permissions

Reading this catalog needs the same read permission as accounts and groups. Changing assignments additionally requires role-management permission, and you can only grant roles you're allowed to bind yourself: a tenant administrator can't grant Super Admin, or grant anything outside their own tenants.

Be careful here. Nothing stops you from removing your own access or the last Super Admin, and either is irreversible without Material support.

Response Structure

The catalog follows the standard two-part structure: a meta object (with totalCount, limit, hasMore, and nextCursor) and an items array of role objects. The catalog is small and fixed, so this endpoint takes pagination only and no filters.

Want a walkthrough?

Review Hello World.

Pagination and Rate Limiting

• Material APIs use cursor-based pagination: pass the nextCursor value from one response as the cursor parameter in the next request.
• The limit parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.
• When hasMore is false and nextCursor is null, you've reached the last page.

List Roles

get

Lists the roles that can be assigned to accounts and groups on this instance. Role definitions are built in, so only assignments are managed through the API, using the roles field of the account and group update endpoints. A role ID carries its scope: tenant-scoped IDs require tenants when assigned, while IDs that apply everywhere take none. Instances that disable global roles omit the global IDs entirely. The response contains no tenant IDs.

Authorizations

x-material-client-secretstringRequired

Material Security API key

Query parameters

cursorstringOptional

The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.

Example: eyJ2IjoxLCJvIjoyNSwibCI6MjV9

limitintegerOptional

The maximum number of items to return per page.

Example: 25

Responses

200

Successful response

application/json

400

Bad request: invalid parameters or request body

application/json

401

Unauthorized: missing or invalid API key

application/json

403

Forbidden: the API key doesn't have permission to perform this action

application/json

404

Not found: the requested resource doesn't exist

application/json

429

Too many requests: the client has exceeded a rate limit and should retry later

application/json

500

Internal server error

application/json

get/api/v1/roles

GET /api/v1/roles HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Accept: */*

{
  "meta": {
    "totalCount": 1,
    "limit": 1,
    "hasMore": true,
    "nextCursor": "text"
  },
  "items": [
    {
      "id": "analyst",
      "name": "Analyst",
      "description": "Investigate and respond to issues within assigned tenants.",
      "flavor": "tenant"
    }
  ]
}