Scopes and roles
OAuth scopes
Ten scopes may be requested at authorization time. Anything else is rejected.
| Scope | Grants |
|---|---|
openid | Issues an ID token. Required for OIDC |
profile | Name and image on the user info endpoint |
email | Email address and verification status |
offline_access | Issues a refresh token, and adds refresh_token to the client's grant types |
account:read | List your linked social accounts for the calling project |
account:manage | List, link, and unlink your shared social account bindings |
project:read | Product scope — see below |
config:read | Product scope — see below |
usage:write | Product scope — see below |
billing:manage | Product scope — see below |
Gate checks only account:read and account:manage itself. The four product scopes exist so your
own API can require them on the tokens it accepts; Gate puts them in the token and never interprets
them. They do not unlock anything in Gate's /api/v1, which takes an API key.
The consent screen renders a human-readable line for each.
Audiences
The resource parameter names the API that will accept the token. Gate accepts:
{GATE_BASE_URL}/api— Gate's own APIhttps://api.shelltime.xyzhttps://api.rawback.apphttps://clippingkk.annatarhe.comhttps://athena.annatarhe.com- the MCP server URL of every active project
The first-party product audiences are built into src/server/origins.ts; adding one is a code
change. A project's MCP server URL becomes an audience
within 30 seconds of being set, and stops being one within 30 seconds of being cleared or of the
project or organization being archived.
MCP clients that identify themselves with a Client ID Metadata Document must send a resource
that is a project's MCP server URL, and may only request openid, profile, email, and
offline_access. See MCP servers.
Token lifetimes and prefixes
| Token | Lifetime | Prefix |
|---|---|---|
| Authorization code | 300 s | — |
| Access token (user) | 600 s | gate_at_ when opaque |
| Access token (machine to machine) | 300 s | gate_at_ when opaque |
| ID token | 600 s | — |
| Refresh token | 2,592,000 s (30 days) | gate_rt_ |
| Client secret | No expiry | gate_cs_ |
| API key | Until revoked or expiresAt | gate_sk_ |
Signing keys are ES256 and rotate every 30 days, with the previous key honoured for a further 30.
Custom claims
Four namespaced claims, advertised in claims_supported:
https://evonia-gate.annatarhe.com/organization_id
https://evonia-gate.annatarhe.com/project_id
https://evonia-gate.annatarhe.com/environment_id
https://evonia-gate.annatarhe.com/resourceorganization_id comes from the client's reference id, project_id and environment_id from its
registration metadata, and resource from the request.
The role matrix
Every member of an organization holds one of five roles. A role applies to every project in the organization.
| Role | Can |
|---|---|
owner | Everything, including archiving the organization. |
admin | Everything except archiving the organization. |
developer | Builds projects: settings, config, and usage. Cannot reveal secrets or manage keys. |
billing | Read-only, plus Stripe, plans, checkout, and entitlement grants. |
viewer | Read-only. Secret values stay masked. |
What each permission allows:
| Permission | Allows |
|---|---|
organization:update | Update organization settings. |
organization:delete | Archive or restore the organization. |
project:read | Read projects, environments, credentials metadata, and the audit log. |
project:write | Create projects and change their settings. |
project:delete | Archive or restore projects. |
credentials:manage | Create and revoke API keys, OAuth clients, and social login settings. |
config:read | Read configuration. API keys also receive secret values. |
config:reveal | Reveal secret values in the dashboard. |
config:write | Create, update, archive, and restore configuration. |
billing:read | Read Stripe settings, plans, subscriptions, and entitlements. |
billing:write | Manage Stripe settings and plans, start checkout, cancel, and grant entitlements. |
usage:read | Read usage analytics. |
usage:write | Record usage events. |
users:write | Remove, restore, or delete a product's end users. |
Which role holds which permission:
| Permission | owner | admin | developer | billing | viewer |
|---|---|---|---|---|---|
organization:update | ✓ | ✓ | |||
organization:delete | ✓ | ||||
project:read | ✓ | ✓ | ✓ | ✓ | ✓ |
project:write | ✓ | ✓ | ✓ | ||
project:delete | ✓ | ✓ | |||
credentials:manage | ✓ | ✓ | |||
config:read | ✓ | ✓ | ✓ | ✓ | ✓ |
config:reveal | ✓ | ✓ | |||
config:write | ✓ | ✓ | ✓ | ||
billing:read | ✓ | ✓ | ✓ | ✓ | ✓ |
billing:write | ✓ | ✓ | ✓ | ||
usage:read | ✓ | ✓ | ✓ | ✓ | ✓ |
usage:write | ✓ | ✓ | ✓ | ||
users:write | ✓ | ✓ |
A member may hold several roles, written as a comma-separated list; any of them can grant a permission. Roles are fixed — organizations cannot define their own.
API key scopes
An API key holds one or more of these scopes, and every key can read its own project and
environments without one. * grants every scope in this list, never a permission outside it.
| Scope | Allows |
|---|---|
config:read | Read configuration. API keys also receive secret values. |
config:write | Create, update, archive, and restore configuration. |
usage:read | Read usage analytics. |
usage:write | Record usage events. |
billing:read | Read Stripe settings, plans, subscriptions, and entitlements. |
billing:write | Manage Stripe settings and plans, start checkout, cancel, and grant entitlements. |
users:write | Remove, restore, or delete a product's end users. |
* | Every API key scope. |
A key is bound to one project, and optionally one environment. Organization routes, project settings, credentials, and secret reveal are for people only. See API keys.