Scope grants

Consumers request Optional and Restricted scopes from their subscription in the API Portal. You approve or decline those requests from the dashboard under Consumers, Requests, or on the subscription itself. On Keycloak and Auth0, an approved scope is added to the consumer's existing OAuth2 client, so no new credentials are issued.

How does a consumer request an Optional scope?

In the API Portal, the consumer opens the subscription, finds the scope in the Available section, and clicks Request Access. No justification is required. The request lands in your queue with a PENDING status.

1. The consumer opens the subscription in the API Portal. Its scopes are listed in four sections: Your Access, Pending Requests, Available, and Requires Approval.
2. In the Available section, they locate the scope they want.
3. They click Request Access. While the request is in flight the button reads Requesting….
4. A confirmation appears: "Request submitted for {scope}".
5. The scope moves to Pending Requests with a PENDING badge and the note "Awaiting approval".

How does a consumer request a Restricted scope?

Restricted scopes sit under Requires Approval and need a written reason. The consumer clicks Request with Reason, answers Why do you need this access?, and clicks Submit. The justification travels with the request to the admin.

1. The consumer opens the Requires Approval section. Each scope there is marked "Requires business justification".
2. They click Request with Reason next to the scope.
3. A form opens with the prompt Why do you need this access? and the placeholder "Briefly describe your use case and any risk mitigations…".
4. They type a justification. The form recommends a minimum of 20 characters. Submit stays disabled until the field has text.
5. They click Submit. While saving, the button reads Submitting….
6. The scope moves to Pending Requests with a PENDING badge, and the consumer's own justification is shown back to them.

Where do admins approve or decline scope requests?

In the dashboard, open Consumers, Requests and select the Access tab. Each row shows the requester, the subscription, the requested scope, the plan, and any justification. Use Approve or Decline on the row.

1. Go to Consumers, Requests in the dashboard sidebar.
2. The tabs read All, Registration, Subscription, Access, each with a count. Open Access to see only scope requests, or use All to see every pending request together.
3. Each row shows the requester's name, the subscription and email, the action line "Requests {scope} on {plan}", and, for Restricted scopes, the consumer's justification in quotes.
4. To grant the request, click Approve. The row confirms with Approved.
5. To turn it down, click Decline, optionally add a reason in Reason (optional), then click Confirm Decline. The row confirms with Declined.

You can also approve and decline from the subscription itself. See How do you manage one subscription's scopes?

Can admins act on several requests at once?

Yes. Select the request rows and the action bar appears at the top. Click Approve Selected to grant them all, or Decline Selected to add one shared reason and Confirm Decline. Each request is processed on its own and shows its own result.

The action bar reports "{count} selected". During a batch each row moves through Queued, then Approving… or Declining…, then Approved or Declined. If a row fails, it stays selected as Failed with the error, so you can retry it without reselecting the rest.

How do you manage one subscription's scopes?

Open the subscription under Consumers → Subscriptions and select its Scopes tab. It lists scopes that need a sync, pending requests, and current grants. From there you can approve or decline requests, grant extra scopes, revoke grants, and retry a sync.

The Scopes tab appears when the subscription's plan has saved access control. The tab has up to three sections:

To grant a scope nobody requested, click Grant scope in Current Grants. The Grant additional scope dialog has two lists:

• From this plan: the plan's Optional and Restricted scopes that the subscription does not hold yet.
• Beyond this plan: scopes on your Authorization Server that the plan does not include, tagged Not part of this plan.

Select the scopes and click Grant {count}. The grant takes effect at once, with no request step.

When a subscription has pending requests, it also shows a Requests ({count}) tab with the same approve and decline actions.

What happens to a consumer's credentials when you approve a scope?

Nothing changes about their credentials. On Keycloak and Auth0, Apiable binds the new scope to the subscription's existing OAuth2 client. The consumer keeps the same client ID and secret and receives the scope on their next token.

Apiable saves the decision first, then updates the client. If that update does not complete, the approval still stands and the scope moves to Needs Sync on the subscription's Scopes tab. The consumer sees a GRANTED badge with a "Syncing…" note until the update lands.

Apiable does not retry on a schedule. Retry the scope with Retry sync. Apiable also tries again when the subscription's credentials change, for example when they are regenerated or the subscription is promoted to production.

Who gets notified about scope requests?

Apiable emails the plan's approval group when a consumer requests a scope, or your portal's default approval group if the plan has none. It emails the consumer when a request is approved, declined, or revoked, including a scope you grant from the dashboard.

You can change their wording under Portal Settings → Templates, on plans that include email templates. A template that is switched off is not sent. See Approval groups and Email domain and templates.

What does a consumer see after a decision?

The consumer's scope sections update to reflect the outcome, and a notice tells them what happened.

Which API calls manage scope grants?

Two endpoints. The first requests a grant on a subscription. The second approves, declines or revokes a grant, or retries a grant that needs a sync.

Troubleshooting

Match the message or state to the fix.

Where to next