AI clients and agents
Connect an unattended agent with a service credential
Give an AI agent that runs on its own, such as a nightly job, a credential for one Ahamo app, with an expiry date and optional address limits.
On this page
A service credential lets an AI agent that runs without you, such as a nightly check or a build pipeline, use Ahamo's AI client tools for one app. Nobody signs in in a browser, because the agent sends the credential with each call.
Availability. On the Team plan and higher, in the workspace that holds the app. An organisation's administrator can turn service credentials off under Rules › People's own AI clients › Service credentials.
When to use it
- An agent on a server or in a scheduled job should read an app's logs, run checks or propose changes.
- You can't open a browser where the agent runs.
When you work with the agent yourself, in an editor or a terminal, sign in with OAuth instead.
How to use it
Make the credential
- Open Account settings › Service credentials and select New service credential.
- Enter a Name that says what the agent does, such as
Nightly log check. - Choose the App. You can choose any app you may edit.
- Tick Let it make changes in development only if the agent should propose changes. Leave it unticked to read only.
- Set Expires on to at least five minutes and at most a year from now.
- Optionally, fill in Only from these addresses with the IP addresses or ranges the agent calls from, separated
by commas, such as
203.0.113.10, 198.51.100.0/24. Leave it empty to allow any address. - Select Make credential and copy it. Ahamo shows it only once, then select I copied it.
The credential is then listed as For the app, with its expiry date.
Store it where your agent keeps secrets, such as an environment variable named AHAMO_CREDENTIAL. Never put it in
code, a committed file or a browser.
Give it to the agent
The agent calls Ahamo's address with the credential as a bearer token:
Authorization: Bearer <your service credential>A credential that may make changes also needs ?read_only=false on the address, the same as a signed-in client.
https://mcp.ahamo.ai/mcp?read_only=false. The credential already names its app, so the agent doesn't need
app_id.
For Claude Code, for example in a scheduled job, put Ahamo in the project's .mcp.json and let Claude Code read the
credential from the environment, so the file holds no secret:
{
"mcpServers": {
"ahamo": {
"type": "http",
"url": "https://mcp.ahamo.ai/mcp",
"headers": {
"Authorization": "Bearer ${AHAMO_CREDENTIAL}"
}
}
}
}For Codex CLI, name the environment variable that holds the credential in ~/.codex/config.toml:
[mcp_servers.ahamo]
url = "https://mcp.ahamo.ai/mcp"
bearer_token_env_var = "AHAMO_CREDENTIAL"With any other agent or script, send one MCP request per call. To check the credential, ask who it acts as. This runs on your server, never in a browser:
curl -s https://mcp.ahamo.ai/mcp \
-H "Authorization: Bearer $AHAMO_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"me","arguments":{}}}'The answer gives your name, the app's workspace, and a connection that names the app and whether it reads only.
What a credential may do
- It works for its one app, and acts with at most your access to it.
- It never changes production. Production changes only through
publish, under the workspace's approvals. - Its calls spend the workspace's credits in the same way as a signed-in client's, and each one is in the audit log.
- It stops on its expiry date, when you revoke it, when you reset your password or are signed out everywhere, when the workspace's plan no longer includes service credentials, or when your organisation turns them off.
Revoke a credential
- Your own in Account settings › Service credentials › Revoke.
- Anyone's in a workspace, as a workspace owner or admin opens Security › AI access, finds it under Service credentials, and selects Revoke, for example when someone leaves or a credential leaks.
A revoked credential stops working at once. To change a credential's app, rights or addresses, make a new one and revoke the old one.
Plans and limits
| Free | Pro | Team | Enterprise | |
|---|---|---|---|---|
| Service credentials | — | — | Yes | Yes, as your organisation allows |
| Limit | Value |
|---|---|
| Lifetime | 5 minutes to 365 days |
| Address limits | Up to 20 addresses or ranges |
| Apps per credential | 1 |
| Calls | 120 a minute per person, shared with your signed-in clients |
Troubleshooting
"This workspace's plan no longer includes service credentials…". The workspace left the Team plan. Someone who manages billing can change the plan under Plans; the credential works again while it hasn't expired.
"This service credential may not be used from this address…". The agent called from an address that isn't in Only from these addresses. Make a new credential with the right addresses and revoke the old one.
"Service credentials are part of the Team plan." The app's workspace is on Free or Pro. Upgrade the workspace, or use a signed-in client.
"Your organisation does not let people make service credentials." An organisation administrator can allow them under Rules.
Calls fail with "unauthorized" (401). The credential expired, was revoked, or ended with a password reset or sign-out everywhere. Make a new one.
"This connection is read-only…". Add ?read_only=false to the address. If the credential was made without
Let it make changes in development, make a new one with it.