Skip to main content
AgentRail uses bearer token authentication. When you create an agent with agentrail agent create, the CLI generates a scoped API key and writes it — along with your base URL — to ~/.agentrail/agent.env. You load that file before starting your coding agent, and it handles authentication automatically.

​
Where your credentials live

After running agentrail init and agentrail agent create, your credentials are stored in ~/.agentrail/agent.env. The file looks like this:
AGENTRAIL_BASE_URL is the address of your local AgentRail API. AGENTRAIL_API_KEY is the bearer token your agent uses to authenticate.
The AGENTRAIL_API_KEY value starts with ar_live_. This is the secret token you pass as the bearer credential. Do not confuse it with the key identifier, which starts with akey_ and is returned separately. The akey_ value is an ID, not a secret.

​
Load credentials before starting an agent

Source the env file in the terminal where you launch your coding agent:
For managed local agents, agentrail server start loads these files automatically. Manual loading is only needed when you launch an agent outside the server-owned supervisor.

​
Pass the token in HTTP requests

When calling the AgentRail API directly, pass the token in the Authorization header:
Example with curl:

​
API key scopes

Each agent key is scoped to only the operations it needs. When you create an agent, the wizard selects appropriate scopes. If you need to change permissions later, use agentrail agent update:
The available scopes are:
Do not assign auth:admin to worker agents. This scope lets the key create and rotate other API keys. Reserve it for setup scripts and operator tooling only.

​
Auth errors

Your request is missing a token or is using the wrong value. The most common cause is passing the key identifier (akey_...) instead of the secret bearer token (ar_live_...).Check that AGENTRAIL_API_KEY is set and starts with ar_live_:
If the env var is empty, re-source your agent env file:
Your token is valid but lacks the scope required for the route you called. Create a new key that includes the required scope, or update the agent’s permissions with:
Each route in the API reference lists the minimum required scope.
Run agentrail doctor after any auth change. Doctor verifies that your agent key can authenticate and that /tasks/mine returns assigned work.