Authorization Servers

An Authorization Server is your OAuth2 provider: the system that issues access tokens and holds your scope definitions. You connect it once under Integrations → Authorization Servers, then use it for your gateways and plans. It is the prerequisite for scope-based access control on OAuth2 plans.

What is an Authorization Server in Apiable?

It is the OAuth2 system that issues your API access tokens and stores your scope definitions. Apiable registers a client on it for each subscription and gives that client the scopes the subscription holds.

Your gateway then validates the tokens the server issues. The Authorization Server is where tokens come from. The gateway is where they are checked.

How is an Authorization Server different from an Identity Provider?

An Authorization Server issues the OAuth2 tokens your gateway validates for machine-to-machine API calls. An Identity Provider signs people in to your API Portal. They solve different problems and are configured separately.

Which authorization servers can you connect?

Keycloak, Auth0 and Duende IdentityServer. Amazon Cognito and Okta are listed as Coming Soon and cannot be selected. Duende connects for registration only, with the limits described below.

How does Apiable create a client for each subscription?

When a developer subscribes to a plan that uses an Authorization Server, Apiable registers an OAuth2 client for that subscription on your server and gives it the plan's Active scopes. Sandbox credentials get a separate client.

This applies to plans whose security method is OAuth 2.0 Client Credentials with Client Secret Basic or with Private Key JWT. Private Key JWT works with a Keycloak server only. With Auth0 or Duende, use Client Secret Basic.

How Apiable registers the client, and what happens when access changes later, depends on the provider:

On Keycloak and Auth0, consumers keep their client ID and secret and pick up the new access on their next token.

What is different with Duende IdentityServer?

Duende sets a client's scopes once, when the client is registered, and Apiable cannot change or delete the client afterwards. Anything that changes a client after registration needs a manual step in IdentityServer.

• New subscriptions get the plan's Active scopes at registration. This needs no manual step.
• Approving an Optional or Restricted request, granting a scope from the dashboard, or revoking one does not change the client. Make the same change in IdentityServer.
• When a subscription is cancelled or its credentials are regenerated, the previous client stays in IdentityServer. Delete it there.
• Sync with Auth Server cannot read or write scopes on Duende, and the plan's warning about scopes missing from the server does not appear. Define your scopes in IdentityServer yourself.

Connect Duende IdentityServer covers the setup and each manual step.

How do you connect an Authorization Server?

Open Integrations → Authorization Servers, choose + Add AuthZ, pick your provider, fill in the form and click Save. Then test the connection and register a test client from the server's page.

1. Open Integrations → Authorization Servers and choose + Add AuthZ. You can also start from the provider's card on the Integrations page.
2. On Select Authorization Server type, select Keycloak, Auth0 or Duende, then choose Connect Authorization Server.
3. Fill in the provider's fields. Each Authorization Server needs a unique name.
4. Click Save. The server's page opens, and Apiable runs OIDC discovery in the background. The results appear under Discovered Auth Methods.
5. Click Test Connection. The status reads Connected, Error or Not tested.
6. Click Register Test Client to check that Apiable can register a client. Delete the test client in your provider afterwards, because Apiable does not remove it.

Apiable keeps the client IDs and secrets you enter in a secrets store, separate from the rest of the connection settings.

What does each provider need?

Each provider asks for different connection fields, and each needs an account on your server that Apiable signs in with. The task pages walk through every field and permission.

Why can the connection test pass when scope binding fails?

Test Connection only reads your server's public discovery document. Register Test Client only checks that Apiable can create a client. Neither checks the permissions Apiable needs to add scopes to a client, so grant everything your provider's page lists before you publish a plan.

When those permissions are missing, new subscriptions still receive credentials, but their tokens carry none of the plan's scopes. The dashboard and the API Portal still list the plan's Active scopes as granted, so check an issued token when you test.

How do you point a gateway at an Authorization Server?

Open the gateway under Integrations → API Gateways, go to its Authorization tab, choose Authorization Server under What handles OAuth flows?, pick your server and click Save Changes. Gateway-bound plans on that gateway can then use scopes.

1. Under What handles OAuth flows?, choose Authorization Server. The other option, Gateway-native only, is limited to Client Credentials with no user flows.
2. In the picker that appears, select your server, or use + Add new Authorization Server.
3. Under Product-level governance, choose Free choice or Locked to this pairing. Locked means every plan bound to this gateway must use this gateway's Authorization Server.
4. Click Save Changes.

A Gateway-bound plan can use scopes only when its gateway's handler is Authorization Server. On a Gateway-native only gateway, the plan's Access Control tab shows the Authorization Server as Not applicable, because the gateway handles authentication itself. Catalog-bound plans do not depend on a gateway setting.

How do you bind an Authorization Server to a plan?

On the plan's Access Control tab. Apiable selects the server for you when your account has only one, or when the plan's gateway sets or locks one. Otherwise, choose it where the tab asks you to Select an Authorization Server.

A plan that uses a server offers the methods listed under Discovered Auth Methods on its Security tab. See Assign scopes to a plan for the full plan setup, and Scopes for how a scoped request is authorized end to end.

What happens when you delete an Authorization Server?

Delete integration on the server's page removes the connection and its stored credentials, and it cannot be undone. The confirmation does not list the plans that use the server, so check your plans' Access Control tabs first.

After the server is deleted, Apiable can no longer remove the clients it registered there. When those subscriptions are cancelled, delete their clients in your provider.

Where to next