Scopes

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 live in Resource Groups under Catalog → Resource Groups. You can add them with New Group, bring them in with Import/Export or Sync with Auth Server, or let Create with Wizard propose them from your API catalog. See Resource groups and scopes.

A scope reaches a plan through the APIs it is attached to. The plan's Access Control tab lists every scope attached to at least one of the plan's APIs.

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

You attach scopes to your APIs and assign them on 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.

1. Define scopes and attach each one to the APIs it protects.
2. For a Gateway-bound plan, set the gateway's OAuth handler to Authorization Server on its Authorization tab.
3. On the plan's Access Control tab, select the Authorization Server and set each scope's state.
4. When a developer subscribes, Apiable registers an OAuth2 client for that subscription on your Authorization Server, with the plan's Active scopes.
5. The consumer exchanges their credentials for an access token whose scope claim reflects what they hold.
6. 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. Every scope starts as Active.

The plan defines what subscribers receive automatically and what they can request. An admin can also grant one subscription an extra scope from its Scopes tab, including a scope that exists on your Authorization Server but is not part of the plan. See Scope grants.

Which authorization servers can issue scoped tokens?

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

With Duende, Apiable can only set a client's scopes when it registers the client, so later changes need a manual step in IdentityServer. See Authorization Servers for the connection steps and how Apiable registers a client per subscription.

How does a consumer get and extend their access?

After subscribing, a consumer receives OAuth2 client credentials and exchanges them at your Authorization Server's token endpoint for a scoped token. They request more access in the API Portal. On Keycloak and Auth0, approved scopes are added to their existing client, with no new credentials.

In the API Portal, a consumer uses Request Access for an Optional scope or Request with Reason for a Restricted one. You approve or decline from Consumers → Requests.

The token endpoint is your Authorization Server's, not Apiable's:

For Private Key JWT subscriptions, the API Portal shows this address as Token endpoint. A Client Secret Basic request looks like this; check your server's documentation for any extra parameters it expects:

curl -X POST "$TOKEN_ENDPOINT" \
  -d grant_type=client_credentials \
  -d scope="payments.read payments.write" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

What do I need before I start?

The feature on your plan, a connected Authorization Server, a gateway pointed at it for Gateway-bound plans, and scopes attached to your APIs.

1. Scope-based access control on your plan (Resource Groups appears under Catalog).
2. A connected Authorization Server, Keycloak, Auth0 or Duende IdentityServer, under Integrations → Authorization Servers.
3. For a Gateway-bound plan, its gateway's OAuth handler set to Authorization Server.
4. Scopes defined under Catalog → Resource Groups and attached to your APIs.

Where to next