API Reference
Getting Started
Core Concepts
Backend API — Guides
Frontend API — Guides
OAuth & OpenID Connect — Guides
Enterprise: SSO & SCIM — Guides
Webhooks — Guides
SDKs
Backend API (BAPI)
Frontend API (FAPI)
Dashboard API
Public API
SCIM
OIDC
Platform

Roles

AdminUpdated Sep 11, 2026

Roles

Dashboard API — authenticated by an Atlas console (platform-instance) session, not a key.

5 routes. Each row is one endpoint with its explanation and whether it honours the Idempotency-Key header.

Method & path

Idem

Explanation

GET /v1/dashboard/accounts/:accountId/instances/:instanceId/roles

Roles with membership counts and permissions, plus which roles grant each permission.

POST /v1/dashboard/accounts/:accountId/instances/:instanceId/roles

Create a custom role. Keys are namespaced org: and may not use sys_.

PATCH /v1/dashboard/accounts/:accountId/instances/:instanceId/roles/:roleId

Relabel a role. The key is immutable because it appears in issued tokens.

PUT /v1/dashboard/accounts/:accountId/instances/:instanceId/roles/:roleId/permissions

Replace a custom role permission set. System role sets are fixed.

DELETE /v1/dashboard/accounts/:accountId/instances/:instanceId/roles/:roleId

Delete a role, optionally reassigning its members first with ?reassign_to.

Was this page helpful?