Set Up ACP with Auth0
This guide takes you from creating an Auth0 API to seeing a verified user identity on your first tool call. Auth0 signs a token for each user, and ACP checks that token before a call runs.
What you need
- An Auth0 account (free tier works)
- An ACP Cloud workspace (sign up)
Step 1: Create an Auth0 API
In the Auth0 Dashboard, go to Applications → APIs → Create API.
| Field | Value |
|---|---|
| Name | ACP Gateway (or anything descriptive) |
| Identifier (Audience) | https://api.agenticcontrolplane.com/your-slug |
| Signing Algorithm | RS256 (required, ACP rejects HS256) |
The identifier becomes the aud claim in the token. ACP checks it on every request.
Step 2: Configure permissions
Under your API’s Permissions tab, add the scopes your tools will require:
salesforce:read
salesforce:write
github:read
github:write
slack:read
slack:write
Enable RBAC
Go to your API’s Settings tab and turn on:
- Enable RBAC
- Add Permissions in the Access Token
Now each user’s token carries a permissions array with the permissions of their role.
Step 3: Set up roles
Go to User Management → Roles and create roles that match your team:
| Role | Permissions |
|---|---|
| Sales (Read Only) | salesforce:read |
| Sales (Full Access) | salesforce:read, salesforce:write |
| Developer | github:read, github:write, slack:read |
| Admin | All permissions |
Assign users to roles. When they sign in, their token lists their role’s permissions.
Step 4: Configure ACP
In your ACP dashboard, go to Settings → Identity Providers and enter:
| Field | Value |
|---|---|
| Issuer | https://your-tenant.auth0.com/ |
| Audience | https://api.agenticcontrolplane.com/your-slug |
| JWKS URI | Leave blank |
That is the whole setup. There are no claim-mapping fields. ACP reads the scope claim (a space-separated string) and the permissions array, and checks required scopes against those two.
With the JWKS URI blank, ACP looks for your signing keys at <issuer>/.well-known/jwks.json, which is where Auth0 serves them.
How Auth0 claims show up in ACP
| Auth0 claim | What ACP does with it |
|---|---|
sub |
Identifies the user on every log row, for example auth0\|8f3a2b1c9d4e5f6a |
iss, aud |
Must match the issuer and audience you entered above |
scope |
Checked against a tool’s required scopes |
permissions |
Checked against a tool’s required scopes |
org_id |
Available to your ABAC rule conditions, if the token has it |
Step 5: Configure tool scopes
In Policies → Tool Scopes, map permissions to tools:
{
"salesforce.query": ["salesforce:read"],
"salesforce.createRecord": ["salesforce:write"],
"github.listRepos": ["github:read"],
"github.createIssue": ["github:write"]
}
When a user calls salesforce.query, ACP checks that their token has salesforce:read in permissions (or in scope). If it doesn’t, the call is rejected with a JSON-RPC error, code -32004 Insufficient scope. The error.data field lists the required, have and missing scopes.
Step 6: Test the flow
Using the ACP playground
Go to Tools → Playground in the dashboard. Pick a tool, enter test input, and run it. The playground uses your dashboard sign-in, and you see the decision right away.
Using an MCP client
Point Claude Desktop or any MCP client at https://api.agenticcontrolplane.com/your-slug. When you sign in, Auth0 issues a token. ACP verifies it and allows or rejects each call based on your permissions.
Check the audit log
Open Logs in the dashboard. A row looks like this:
{
"sub": "auth0|8f3a2b1c9d4e5f6a",
"tool": "salesforce.query",
"scopes": ["salesforce:read", "salesforce:write"],
"ok": true,
"latencyMs": 142
}
The sub is the Auth0 user ID, and the scopes come from the token.
Auth0 Organizations
If you use Auth0 Organizations, tokens include an org_id claim. ACP passes it to your ABAC rules, so you can write a rule that allows or blocks a tool based on org_id.
ACP does not split data by org_id on its own. Separation between customers is by workspace: a token must carry your workspace’s configured issuer and audience to be accepted.
Troubleshooting
“Invalid token: unexpected iss claim”
The issuer in ACP doesn’t match the one in the token. Auth0 issuers end with a slash (https://your-tenant.auth0.com/). Copy the iss value from a decoded token and compare it with what you entered.
“Insufficient scope” The token doesn’t include the required permission. Check that RBAC is enabled on the API, that “Add Permissions in the Access Token” is on, and that the user has a role with the permission.
“Missing bearer token” The MCP client isn’t sending the Authorization header. Set the client up to use OAuth.
Back to guides · Set up Okta → · Set up Entra ID →
Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex