Integrations
Connect Auth0
Connect Auth0 as an Authorization Server in Apiable. Enter your Domain, API Audience and Management API credentials, grant the nine Management API permissions scope binding needs, then test the connection.
You connect Auth0 as an Authorization Server under Integrations → Authorization Servers. You enter your tenant domain, the API audience your tokens target, and the credentials of a Management API application. Apiable then registers a Machine to Machine application for each subscription and grants it the plan's scopes on your API.
Where do you connect Auth0?
Go to Integrations → Authorization Servers, choose + Add AuthZ, select Auth0 on the Select Authorization Server type screen, then choose Connect Authorization Server.
- Open Integrations → Authorization Servers.
- Choose + Add AuthZ.
- On Select Authorization Server type, select Auth0.
- Choose Connect Authorization Server. The Auth0 connection form opens, titled Auth0 Configuration.
What does each Auth0 field mean?
The form has a name, a Tenant section and a Management API Credentials section. Fill in the fields, then save.
| Field | Section | What to enter |
|---|---|---|
| Name | (top) | A label for this connection inside Apiable. Required, and unique across your Authorization Servers. |
| Domain | Tenant | Your Auth0 tenant domain with no scheme, for example myorg.us.auth0.com. Required. Apiable derives the token endpoint https://{domain}/oauth/token and the Management API address from it. |
| API Audience | Tenant | The identifier of the Auth0 API your access tokens target, for example https://api.example.com. Optional in the form, but needed for scopes. Read the section below before leaving it blank. |
| Client ID | Management API Credentials | The Client ID of the Machine to Machine application Apiable uses to call the Auth0 Management API. Required. |
| Client Secret | Management API Credentials | The Client Secret of that application. Required. |
Which Management API permissions does the application need?
Nine permissions. The four client permissions let Apiable register and manage each subscription's application. The four client grant permissions let it bind scopes. read:resource_servers lets it read your API's scopes. Grant all nine on the application's Management API authorization in the Auth0 Dashboard.
| Permission | What Apiable uses it for |
|---|---|
create:clients | Register an application for each subscription, and the test client. |
read:clients | Look up a subscription's application. |
update:clients | Update a subscription's application when its registration changes. |
delete:clients | Delete a subscription's application when the subscription is cancelled or its credentials are regenerated. |
read:client_grants | Read which scopes an application holds on your API. |
create:client_grants | Give an application its first scopes on your API. |
update:client_grants | Add or remove scopes on an application's grant. |
delete:client_grants | Remove the grant when an application's last scope is removed. |
read:resource_servers | Read the permissions defined on your API, for Sync with Auth Server and the plan's warning about scopes missing from the server. |
Does the API Audience matter?
Yes, if you use scopes. The form lets you save Auth0 without an API Audience, but scope binding does nothing without it. With no audience set, Apiable issues no client grant, the issued tokens carry no scopes, and nothing is enforced.
Where do your scopes live in Auth0?
As permissions on the Auth0 API whose identifier is your API Audience. Define every scope your plans use there. Apiable reads them for Sync with Auth Server, but it cannot create them in Auth0.
Push to Auth Server does not create permissions on Auth0. To hand the list over, use Export Scopes on the Resource Groups page or on a plan's Access Control tab, then add the permissions to your API in the Auth0 Dashboard. See Resource groups and scopes.
How do you save and test the connection?
Click Save. The server's page opens and Apiable runs OIDC discovery for the tenant in the background. Then click Test Connection to confirm the tenant is reachable. The status reads Connected, Error, or Not tested.
- Click Save. A new connection shows Save. When you edit a saved one, the button reads Save & Test Connection and runs a test after saving.
- The server's page opens. The results of OIDC discovery appear under Discovered Auth Methods.
- Click Test Connection. Apiable reads your tenant's OpenID configuration at
https://{domain}/.well-known/openid-configuration. - Read the status: Connected means the tenant responded. Error shows the start of the error message. Not tested means no test has run yet.
Connected means the tenant answered. It does not check the Management API credentials or their permissions.
How do you confirm client registration works?
On the saved connection, click Register Test Client. Apiable creates a Machine to Machine application named test-client- followed by the connection's ID, and shows its Client ID and Client Secret once.
This confirms your Management API credentials and create:clients. It does not confirm the client grant permissions. Delete the test application in the Auth0 Dashboard when you are done, because Apiable does not remove it.
Troubleshooting
Match the status or message to the fix.
| What you see | What to do |
|---|---|
| Status Not tested | No connection test has run yet. Open the server and click Test Connection. |
| Status Error with "Auth0 returned ..." | Auth0 answered, but the discovery address returned an error status. Check the Domain value. |
| Status Error with "Failed to reach Auth0 at ..." | Apiable could not reach the tenant. Check the Domain for typos and that it has no https:// prefix. |
| The Name field says "An authorization server named '{name}' already exists." | Each Authorization Server needs a unique name. Choose another name and save again. |
| Tokens carry none of the plan's scopes, although the plan shows them as Active | Set the API Audience, and grant the four client grant permissions. Subscriptions created before the fix keep an application without those scopes until their credentials are regenerated. |
| Register Test Client returns an error | The Management API call failed. Check the Client ID and Client Secret, and that the application has create:clients. |
| Push to Auth Server creates no permissions on Auth0 | Apiable cannot create permissions on Auth0. Export your scopes and add them to your API in the Auth0 Dashboard. |
| Discovered Auth Methods shows a discovery error | Apiable could not read the tenant's discovery document. Check the Domain, then click Refresh. |