Do Apiable scopes use colons, like payments:read?

No. Apiable does not impose a naming convention. Scopes are arbitrary strings such as payments.read or SMART-on-FHIR style patient/Observation.read.

Do consumers get new credentials when they gain a scope?

No. Approved scopes are added to the consumer's existing OAuth2 client in place, so they pick up the access on their next token.

Where do I assign scopes to a plan?

On the plan's Access Control tab, where each scope is set to Active, Optional, or Restricted.

Access control

Scopes

Scope-based access control authorizes API consumers with OAuth2 scopes, so each subscriber gets exactly the access their plan grants instead of an all-or-nothing API key.

Scope-based access control authorizes your API consumers with OAuth2 scopes, so each subscriber receives a token carrying exactly the access their plan grants, instead of an all-or-nothing API key.

What is a scope in Apiable?

A scope is a named permission you define, for example payments.read or patient/Observation.read. Apiable does not impose a naming convention, so use whatever your APIs already expect.

Scopes are organized into Resource Groups in your catalog, under Catalog → Resource Groups. You can add them by hand, Import CSV, Sync from Auth Server, or use the Scope Creation Wizard, which reads your API catalog and proposes a set.

How does a scoped request get authorized, end to end?

You attach scopes to a plan, your authorization server issues a token carrying the granted scopes, and your gateway checks the token against each endpoint before the request reaches your backend.

Define scopes for your APIs (above).
On the plan's Access Control tab, assign each scope a state and select the authorization server that issues tokens.
When a developer subscribes, Apiable registers an OAuth2 client for that subscription, bound to the plan's scopes.
The consumer exchanges their credentials for an access token whose scope claim reflects what they hold.
Your gateway validates the token and enforces the required scope per endpoint.

What do the Active, Optional, and Restricted states mean?

On a plan's Access Control tab every scope gets one state, which decides how a subscriber receives it.

State	Behavior
Active	Every subscriber receives this automatically.
Optional	Subscribers can request this.
Restricted	Requires approval with business justification.

The plan sets the ceiling of available scopes; each subscription holds a subset.

Which authorization servers can issue scoped tokens?

Keycloak and Auth0 today. Amazon Cognito, Okta, and Duende are listed as coming soon. You connect one under Integrations, then bind it to the plan on the Access Control tab.

See Authorization Servers for the connection steps and how Dynamic Client Registration provisions a client per subscription.

How does a consumer get and extend their access?

After subscribing, a consumer receives OAuth2 credentials and a token endpoint, then exchanges them for a scoped token. They request more access from the portal, and approved scopes are added to their existing client with no new credentials.

In the portal's Your Access view, a consumer uses Request Access for an Optional scope or Request with Reason for a Restricted one. You approve or decline from Consumers → Requests.

POST /oauth2/token

curl -X POST https://<your-token-endpoint>/oauth2/token \
  -d grant_type=client_credentials \
  -d scope="payments.read payments.write" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

What do I need before I start?

Scope-based access control enabled on your account (the Scopes banner appears).
A configured authorization server, Keycloak or Auth0, under Integrations → Authorization Servers.
Scopes defined for your APIs under Catalog → Resource Groups.

Where to next

Assign scopes to a plan

Set each scope to Active, Optional, or Restricted on the plan's Access Control tab.

Authorization Servers

Connect Keycloak or Auth0 to issue the scoped tokens.