Skip to Content
Documentation menu

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:

POST/api/v1/agentsaccount key
json
{
  "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.

FieldMeaning
allowed_actionsThe 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_limitRequests per minute. Over it, requests are denied.
domainSelects 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_idOptional, 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.

CallWhat it does
GET /api/v1/api-keysList keys (id, agent, environment, status, expiry).
POST /api/v1/api-keys/:keyId/rotateIssue a new key and revoke the old one at once.
POST /api/v1/api-keys/:keyId/revokeRevoke 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.

bash
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_id is the key's id (from the key list); client_secret is the key itself.
  • scope narrows the token to some of the agent's actions. It never widens them.
  • end_user_id binds the token to one person with an active consent: every call made with it is then checked against that consent. See End users.
  • audience names the API the token is for (default authentify).
  • Tokens are Ed25519-signed; your own APIs can verify them against /.well-known/jwks.json (or with verifyAuthentifyToken in 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:

bash
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_token

The 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

ScopeHowEffect
One agentPOST /api/v1/agents/:agentId/revoke or the Agents pageEvery later request from it is denied.
Whole accountAccount → 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 agentThe person pauses or turns it offRequests naming that person are denied.
Every change is evidence

Creating, changing, revoking agents and keys, and every policy change, is sealed into the audit chain with who did it.