Skip to Content
Documentation menu

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

POST/api/v2/authorizeagent key or Bearer token
json
{
  "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"
}
FieldRequiredMeaning
actionyesThe action the agent wants to take. Must be in the agent’s allowed actions.
resource.idyesWhat it acts on. Checked against the agent's resource scope. resource.type is optional.
contextnoAnything 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.
endUserIdwhen the agent acts for one personYour id for that person. Checks their consent. See End users.
sessionIdnoYour id for one agent run (1–128 printable characters, no spaces). Groups its requests in the dashboard and in the sealed record.
parentRequestIdnoThe authorizationRequestId of an earlier request this one follows from. It joins that request's session.
audiencenoThe API that will run the action. On allow, the response carries a decision token for it.

The response

json
{
  "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
}
FieldMeaning
decisionallow, deny or escalate. The only field that says whether to act.
reasonWhy, in words. Stable codes for consent: end_user_required, consent_required, consent_paused, outside_consent_scope.
authorizationRequestIdThis request’s id: for status, outcomes, decision tokens and the audit record.
approvalRequestIdOn escalate: the review a person will decide.
endUserCanDecideOn escalate: the person the agent acts for can decide it themselves (single-action approval).
decisionTokenOn allow, when you sent audience: proof for your API, valid 60 seconds.
violationActionOn a scope violation: agent_revoked or agent_flagged.
Fail closed

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

  1. The account: kill switch on, billing on hold, or sandbox trial ended → deny.
  2. The agent: revoked → deny.
  3. The person (if the agent acts for one): no endUserId when the agent requires one, no consent, consent paused, or the action outside what they agreed to → deny.
  4. 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.
  5. 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.
  6. 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

GET/api/v2/authorization-requests/:idaccount key

The 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 audience with the authorize call; the token is in the response.
  • Approved later by a person: the agent calls POST /api/v2/authorization-requests/:id/decision-token with { "audience": "..." }, within 6 days.

At your API, verify it offline against /.well-known/jwks.json, or with the TypeScript SDK:

ts
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

POST/api/v2/authorization-requests/:id/outcomeagent or account key
json
{ "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).