Management API & RBAC

How to protect your own APIs, how the built-in Management API works, how to grant access with roles/scopes, and how machine-to-machine clients authenticate.

Two kinds of API

1. Your product APIs — register each as an API resource; apps request scoped access tokens; your API verifies them.
2. The Authara Management API — the admin/control API for a tenant (create apps, users, roles, connectors, sign-in experience, …). It's what the console calls and what your automation can call.

Both use the same OAuth mechanics: a token with an audience (resource indicator) and scopes.

Register an API resource

Admin console → API resources → create one with:

• Resource indicator — a unique URI that becomes the token audience (e.g. https://api.acme.com).
• Permissions (scopes) — e.g. read:orders, write:orders.

Then verify tokens on your API (see Sessions & tokens). An app requests a token with getAccessToken('https://api.acme.com').

RBAC — roles, permissions, scopes

• Permissions are scopes on an API resource (read:orders).
• Roles bundle permissions (orders-manager = read:orders + write:orders).
• Assign roles to users or M2M apps. Granted permissions become the token's scope.

Define permissions per resource, group them into a few meaningful roles, and assign roles to users — don't grant raw scopes ad hoc.

The Management API (per tenant)

Each tenant has its own Management API, protected by a per-tenant resource indicator and a tenant guard — a token for tenant A's Management API cannot touch tenant B. It's mounted under the admin host ({ADMIN_ENDPOINT}/api/…). Everything the console does is a Management API call.

Machine-to-machine (M2M)

For automation that acts without a user:

1. Create a Machine-to-machine application.
2. Assign it a role with the scopes it needs.
3. Authenticate with the client-credentials grant:

POST {ENDPOINT}/oidc/token
  grant_type=client_credentials
  client_id=<m2m_id>
  client_secret=<m2m_secret>
  resource=<resource-indicator>       # your API, or the Management API resource
  scope=<space-separated scopes>

Use the returned access token as a normal bearer token.

Cross-tenant Management-API access

An admin-tenant credential minting tokens for another tenant's Management API is the model the multi-tenant control plane needs — it's on the roadmap alongside runtime tenant provisioning.

Best practices

• Scope tightly. Never grant a product app the Management API all scope.
• Verify audience. The most common API-auth bug is accepting a token minted for a different resource — always check aud.
• Rotate M2M secrets and keep them in a secrets manager, not in code or CI.
• Rate-limit token and API endpoints at your proxy; audit-log privileged Management API calls.