Guides
Agents & credentials
Every agent is registered once with what it may do. Each has its own key, so every request is attributable to one agent, and one agent can be stopped without touching the others.
Create an agent
Use the setup wizard or Dashboard → Govern → Agents. Over the API, with your account key or a signed-in session:
/api/v1/agentsaccount key{
"customerId": "YOUR_CUSTOMER_ID",
"agent_name": "care-scheduler",
"domain": "healthcare",
"allowed_actions": ["READ_RECORDS", "SCHEDULE_APPOINTMENT"],
"entity_scope": "patient-*",
"rate_limit": 600,
"model_id": "anthropic/claude-sonnet-5"
}The response includes the agent's api_key. It is shown once; store it in your secret manager.
| Field | Meaning |
|---|---|
allowed_actions | The action names this agent may ask for. Anything else is denied as out of scope. Names are yours: use the ones your systems already use. |
entity_scope | * (any resource), one exact id, or a prefix ending in * such as patient-*. A request for a resource outside it is denied as a scope violation. |
rate_limit | Requests per minute. Over it, requests are denied. |
domain | Selects the domain policy. finance can be given limited autonomous authority; in every other domain, in-scope requests always go to human review. See domain policy. |
model_id | Optional, self-reported: which model runs the agent, for your own records. |
Change an agent later with POST /api/v1/agents/:agentId/update (allowed_actions, entity_scope, rate_limit, domain, requires_end_user, end_user_approval). With change approval turned on (Dashboard → Govern → Policies), a change that makes the agent more powerful waits for a second person to approve it; a change that only reduces risk applies at once. Rule changes that could let more calls through are covered the same way (see Rules).
Scope violations
A request for a resource outside the agent's scope is always denied. What happens to the agent is your choice (Dashboard → Govern → Policies → Scope violation handling): auto-revoke (the default) stops the agent immediately; notify only flags it for review. You're emailed either way.
Keys
Agent keys look like aut_sandbox_… or aut_production_…; the prefix picks the environment. Only a hash is stored, so a lost key can't be shown again: rotate it. You can cap how long keys live under Account → Settings.
| Call | What it does |
|---|---|
GET /api/v1/api-keys | List keys (id, agent, environment, status, expiry). |
POST /api/v1/api-keys/:keyId/rotate | Issue a new key and revoke the old one at once. |
POST /api/v1/api-keys/:keyId/revoke | Revoke one key. |
Short-lived tokens (OAuth 2.1)
Optional. Instead of sending the long-lived key on every call, exchange it for a 10-minute access token and send that as Authorization: Bearer. The SDKs mint and refresh tokens for you when given a key id and secret.
curl -X POST https://www.authentify.bz/api/v1/oauth/token \
-d grant_type=client_credentials \
-d client_id=$AUTHENTIFY_KEY_ID \
-d client_secret=$AUTHENTIFY_AGENT_KEY \
-d scope="READ_RECORDS"
# -> { "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 600 }client_idis the key's id (from the key list);client_secretis the key itself.scopenarrows the token to some of the agent's actions. It never widens them.end_user_idbinds the token to one person with an active consent: every call made with it is then checked against that consent. See End users.audiencenames the API the token is for (defaultauthentify).- Tokens are Ed25519-signed; your own APIs can verify them against
/.well-known/jwks.json(or withverifyAuthentifyTokenin the TypeScript SDK).
Agents acting for signed-in users (token exchange)
If your users sign in with Microsoft Entra ID, an agent can present the user's own token instead of an id your app asserts. Register your tenant under Dashboard → Admin → Integrations → Identity provider (or POST /api/v1/identity-providers), then the agent calls the token endpoint with RFC 8693 token exchange:
curl -X POST https://www.authentify.bz/api/v1/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d client_id=$AUTHENTIFY_KEY_ID \
-d client_secret=$AUTHENTIFY_AGENT_KEY \
-d subject_token=$USER_ENTRA_ID_TOKEN \
-d subject_token_type=urn:ietf:params:oauth:token-type:id_tokenThe result is a 10-minute token whose sub is the user and act is the agent. It is only issued if that user has consented to that agent, and it never outlives the user's own token. SDK: exchangeToken().
Stopping agents
| Scope | How | Effect |
|---|---|---|
| One agent | POST /api/v1/agents/:agentId/revoke or the Agents page | Every later request from it is denied. |
| Whole account | Account → Settings → Account kill switch (PUT /api/v1/account/kill-switch) | Every request from every agent is denied at once. The owner or an admin can turn it on; only the owner can turn it off. |
| One person’s agent | The person pauses or turns it off | Requests naming that person are denied. |
Creating, changing, revoking agents and keys, and every policy change, is sealed into the audit chain with who did it.