Guides
Authorizing actions
One call before every action that matters. The answer is allow, deny or escalate, and the request is sealed with the checks that produced it.
The request
/api/v2/authorizeagent key or Bearer token{
"action": "ISSUE_REFUND",
"resource": { "id": "order-88231", "type": "order" },
"context": { "amount": 240.00, "reason": "damaged on arrival" },
"endUserId": "customer-42",
"sessionId": "run-7f3a",
"audience": "https://api.example.com/refunds"
}| Field | Required | Meaning |
|---|---|---|
action | yes | The action the agent wants to take. Must be in the agent’s allowed actions. |
resource.id | yes | What it acts on. Checked against the agent's resource scope. resource.type is optional. |
context | no | Anything a rule or a reviewer needs: amounts, reasons, record details. context.amount is in dollars (major units). Values that look like credentials or regulated identifiers are redacted before storage and listed in contextRedactedPaths; the decision still sees the original. |
endUserId | when the agent acts for one person | Your id for that person. Checks their consent. See End users. |
sessionId | no | Your id for one agent run (1–128 printable characters, no spaces). Groups its requests in the dashboard and in the sealed record. |
parentRequestId | no | The authorizationRequestId of an earlier request this one follows from. It joins that request's session. |
audience | no | The API that will run the action. On allow, the response carries a decision token for it. |
The response
{
"decision": "escalate",
"reason": "Requires human approval",
"authorizationRequestId": "3f0c9a52-...",
"approvalRequestId": "b81e44d0-...",
"escalationTier": "manual_review",
"escalationSlaMinutes": 60,
"endUserCanDecide": true,
"sessionId": "run-7f3a",
"appliedScope": { "allowedActions": ["ISSUE_REFUND"], "resourceScope": "order-*", "rateLimit": 600 },
"ruleMatched": false,
"witness": { "status": "pending", "verifyUrl": "..." },
"latencyMs": 41
}| Field | Meaning |
|---|---|
decision | allow, deny or escalate. The only field that says whether to act. |
reason | Why, in words. Stable codes for consent: end_user_required, consent_required, consent_paused, outside_consent_scope. |
authorizationRequestId | This request’s id: for status, outcomes, decision tokens and the audit record. |
approvalRequestId | On escalate: the review a person will decide. |
endUserCanDecide | On escalate: the person the agent acts for can decide it themselves (single-action approval). |
decisionToken | On allow, when you sent audience: proof for your API, valid 60 seconds. |
violationAction | On a scope violation: agent_revoked or agent_flagged. |
If Authentify can't be reached, times out or returns an error, don't run the action. The SDK's guard() does this for you: it resolves only on allow and throws otherwise.
What is checked, in order
- The account: kill switch on, billing on hold, or sandbox trial ended → deny.
- The agent: revoked → deny.
- The person (if the agent acts for one): no
endUserIdwhen the agent requires one, no consent, consent paused, or the action outside what they agreed to → deny. - Scope: action not allowed, resource outside scope, or over the rate limit → deny. A resource outside scope also revokes or flags the agent, per your violation policy.
- Your rules: the action isn't in a matching rule's action list, the amount is over its cap, or the rule has expired → deny.
- Domain policy: whether a request that passed every check may proceed on its own or goes to a person.
Domain policy and autonomy
A request that passes every check is escalated to a person by default. Agents in the finance domain can be given limited autonomous authority (on the agent, and per rule): below a ceiling, for listed transaction types, they are allowed without review, and the response carries autonomousApprovalReason. Above the ceiling, or with a missing or invalid amount, the request goes to review. In every other domain, in-scope requests always go to a person; nothing is allowed without review.
Rules
Rules live under Dashboard → Govern → Policies (or /api/v1/rules). A rule applies to the calls its condition matches. Its action list replaces the agent's for those calls (so it can add or remove actions), it can cap context.amount, and it can expire on a date; a request it rules out is denied. A rule with an amount limit denies a request that doesn't send an amount. A rule never widens the agent's resource scope or rate limit, and outside finance an action a rule adds still goes to a person. For finance agents, a rule can also set when autonomy applies. Every rule change is sealed into the audit log with who made it and what changed. With change approval on, a rule change that could let more calls through waits for a second person: adding, deleting, turning on or off, re-targeting or re-prioritising a rule (only the first matching rule applies, so these can uncover another), or adding actions to it or loosening its limits. The API answers 202 with pending_approval: true. Edits that only tighten a rule apply at once.
Request status
/api/v2/authorization-requests/:idaccount keyThe request as recorded: decision, the checks that ran, votes, outcome and its witness. GET /api/v2/authorization-requests lists them (?session_id= shows one run). For escalations, prefer a webhook over polling.
Decision tokens
A decision token lets the API that runs the action check, by itself, that Authentify allowed this action. It is an Ed25519-signed JWT (typ authentify-decision+jwt) naming the decision, agent, action, resource, a hash of the context, and the audience. It lives 60 seconds and only one is ever issued per decision.
- Allowed right away: send
audiencewith the authorize call; the token is in the response. - Approved later by a person: the agent calls
POST /api/v2/authorization-requests/:id/decision-tokenwith{ "audience": "..." }, within 6 days.
At your API, verify it offline against /.well-known/jwks.json, or with the TypeScript SDK:
import { verifyAuthentifyDecision } from '@authentify2026/sdk';
const claims = await verifyAuthentifyDecision(token, {
audience: 'https://api.example.com/refunds',
action: 'ISSUE_REFUND',
resourceId: order.id,
context: refundDetails, // the same object the agent sent as context
isReplay: (jti, exp) => seenBefore(jti, exp), // single use
});Or ask Authentify: POST /api/v1/decision-tokens/verify with { token, audience, context } (any of your keys). It also reports whether the agent and the person's consent are still active, and whether the context you send matches the one that was approved. The answer is always HTTP 200 with valid true or false.
Reporting outcomes
/api/v2/authorization-requests/:id/outcomeagent or account key{ "status": "succeeded", "detail": { "refundId": "rf_1029" } }status is succeeded, failed or not_attempted. The report is sealed next to the decision, so the record shows not only what was allowed but what happened. You can require reports to come from your own system and to be signed (x-authentify-signature and x-authentify-timestamp).