{
  "openapi": "3.1.0",
  "info": {
    "title": "Authentify API",
    "version": "2026-11-17",
    "summary": "Authorize AI agent actions before they run, and prove what was decided.",
    "description": "Core endpoints an agent or an institution's backend calls. Your agent asks before it acts; Authentify answers allow, deny or escalate, and seals the decision in a tamper-evident audit log. Authentify never runs the action itself.\n\nSandbox or production is fixed by the credential you send, not by a parameter.\n\nThis file covers the core integration surface. Dashboard-only endpoints (they need a signed-in session) are not listed. See https://www.authentify.bz/docs/api and https://www.authentify.bz/docs.",
    "contact": { "name": "Authentify", "url": "https://authentify.bz" }
  },
  "servers": [{ "url": "https://authentify.bz" }],
  "tags": [
    { "name": "Authorization", "description": "Ask before an agent acts." },
    { "name": "Evidence", "description": "Proof of a decision, and what happened after it." },
    { "name": "Tokens", "description": "Short-lived agent access tokens (OAuth 2.1)." },
    { "name": "Consent", "description": "End-user consent for agents that act for a specific person." },
    { "name": "End users", "description": "Links you send one of your end users: approve one action, or see and manage their agents." }
  ],
  "paths": {
    "/api/v2/authorize": {
      "post": {
        "tags": ["Authorization"],
        "operationId": "authorize",
        "summary": "Ask whether an agent may take an action",
        "description": "Call this before the agent acts. A decision is always returned with HTTP 200: check `decision`, not only the status code. `allow` means your application may run the action, `deny` means it must not, and `escalate` means it is on hold until your approvers decide.",
        "security": [{ "agentApiKey": [] }, { "agentAccessToken": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" }, "example": { "action": "approve_claim", "resource": { "id": "claim-123", "type": "insurance_claim" }, "context": { "claimantTier": "gold" } } } }
        },
        "responses": {
          "200": {
            "description": "The decision.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeResponse" }, "example": { "authorizationRequestId": "authreq_...", "decision": "escalate", "reason": null, "ruleMatched": false, "approvalRequestId": "approval_...", "escalationTier": "manual_review" } } }
          },
          "400": { "description": "The key is not tied to an agent, or `audience` is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing, invalid or expired credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "The access token is not scoped to an agent, or is bound to a different end user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "501": { "description": "An OAP-format response was requested but is not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v2/authorization-requests/{id}/decision-token": {
      "post": {
        "tags": ["Evidence"],
        "operationId": "getDecisionToken",
        "summary": "Get single-use proof of one approved action",
        "description": "After an action is approved, the agent that asked can obtain one short-lived signed token to present to the downstream system (`audience`). Only one token is issued per decision.",
        "security": [{ "agentApiKey": [] }, { "agentAccessToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/AuthorizationRequestId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["audience"], "properties": { "audience": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The system the token is for. Printable characters, no spaces.", "examples": ["https://api.yourbank.com/payments"] } } } } }
        },
        "responses": {
          "200": { "description": "The token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionTokenResponse" } } } },
          "400": { "description": "`audience` is missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing, invalid or expired credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Not the agent that made the request, the request was not approved, the agent is revoked, the account kill switch is active, or the end user's consent no longer covers the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Authorization request not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "Still waiting for approval, or a token was already issued for this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "410": { "description": "The decision is too old to redeem. Request a new authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "501": { "description": "Decision tokens are not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "503": { "description": "Decision tokens are temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v2/authorization-requests/{id}/outcome": {
      "post": {
        "tags": ["Evidence"],
        "operationId": "reportOutcome",
        "summary": "Report what happened after a decision",
        "description": "Records whether the authorized action actually ran. The report is sealed in the audit log. An institution can require reports to come from its own system and to be signed; a signed report sends the `x-authentify-signature` and `x-authentify-timestamp` headers.",
        "security": [{ "agentApiKey": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/AuthorizationRequestId" },
          { "name": "x-authentify-signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Signature over the report, when signed reports are used." },
          { "name": "x-authentify-timestamp", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Timestamp the signature covers. Use a fresh one for each report." }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["succeeded", "failed", "not_attempted"] }, "detail": { "type": "object", "additionalProperties": true, "description": "Optional details about the outcome." } } } } }
        },
        "responses": {
          "200": { "description": "The report was recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorizationRequestId": { "type": "string" }, "outcomeStatus": { "type": "string" }, "reportedBy": { "type": "string", "enum": ["agent", "institution"] }, "signatureVerified": { "type": "boolean" } } } } } },
          "400": { "description": "The body is not JSON or `status` is not an allowed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Invalid credentials or an invalid signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "This institution accepts outcome reports only from its own system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Authorization request not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "This signed report was already received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/oauth/token": {
      "post": {
        "tags": ["Tokens"],
        "operationId": "mintToken",
        "summary": "Get a short-lived agent access token",
        "description": "OAuth 2.1 token endpoint. Use `client_credentials` for an agent's own token, or the RFC 8693 token-exchange grant to act for a signed-in user. Credentials go in the form body.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } }
        },
        "responses": {
          "200": { "description": "The access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } },
          "400": { "description": "Unsupported grant, missing fields, bad scope or audience, or no active consent for the user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } },
          "401": { "description": "Unknown, revoked, expired or incorrect client credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } },
          "403": { "description": "The account kill switch is active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }
        }
      }
    },
    "/api/v1/consent-sessions": {
      "post": {
        "tags": ["Consent"],
        "operationId": "createConsentSession",
        "summary": "Start a consent session for one of your end users",
        "description": "Only needed when an agent acts for a specific person. Call it server to server with your account-level API key (agent keys are refused), then send the person to `widget_url` (a hosted page) or embed the consent widget with `session_id`. Identify the person with `end_user_id`, or with `subject_token` alone. You learn the outcome from the `consent_granted` / `consent_declined` webhook events (`data.detail.end_user_id`), or from the widget's `onApprove` / `onDecline` when you embed it.",
        "security": [{ "accountApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentSessionRequest" }, "example": { "agent_id": "YOUR_AGENT_ID", "customer_id": "YOUR_CUSTOMER_ID", "end_user_id": "customer-42", "scope": ["READ", "TRANSFER"] } } }
        },
        "responses": {
          "200": { "description": "The session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "widget_url": { "type": "string" } } } } } },
          "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "An agent-scoped key was used, or the key does not belong to this `customer_id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v2/approval-requests/{id}/end-user-link": {
      "post": {
        "tags": ["End users"],
        "operationId": "createEndUserApprovalLink",
        "summary": "Get a single-use link for the person to approve or deny one escalated action",
        "description": "For an escalated request that names an end user (`endUserId` on `/api/v2/authorize`). Send `url` to that person (in-app, push, email or SMS). It opens the hosted approval page, where they approve, deny, or deny and pause the agent. Single-use; expires after 30 minutes. Never give it to the agent: whoever holds it can decide the request.",
        "security": [{ "accountApiKeyHeader": [] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The `approvalRequestId` returned by `/api/v2/authorize`." }],
        "responses": {
          "200": { "description": "The link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "end_user_id": { "type": "string" } } } } } },
          "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "An agent-scoped key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "No such approval request on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "The request is already resolved, names no end user, or the agent is not set up for end-user approval (`end_user_approval` off).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v2/end-users/{endUserId}/portal-link": {
      "post": {
        "tags": ["End users"],
        "operationId": "createEndUserPortalLink",
        "summary": "Get a \"my agents\" link for one of your end users",
        "description": "Send `url` to the person. It opens the hosted page `/my-agents`: Connected agents (pause, resume, turn off) and Activity (everything their agents did or tried for them, with a downloadable record), including agents whose access has ended. Works for 1 hour, only in the environment of the key that asked for it, so ask for a fresh one each time the person opens it from your app. A turned-off agent only comes back through a new consent session from you.",
        "security": [{ "accountApiKeyHeader": [] }],
        "parameters": [{ "name": "endUserId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 256 }, "description": "Your own id for the person: the `end_user_id` from their consent session." }],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "type": "object", "properties": { "identity_provider_id": { "type": "string", "format": "uuid", "description": "Only for a person identified through one of your identity providers (token exchange)." } } } } }
        },
        "responses": {
          "200": { "description": "The link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "end_user_id": { "type": "string" } } } } } },
          "400": { "description": "Missing or invalid end user id, or an unknown identity_provider_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "An agent-scoped key was used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "An API key. `/api/v2/authorize` needs an agent-specific key." },
      "agentAccessToken": { "type": "http", "scheme": "bearer", "description": "A short-lived agent access token from `/api/v1/oauth/token`." },
      "accountApiKey": { "type": "http", "scheme": "bearer", "description": "Your account-level API key, sent as `Authorization: Bearer <key>`." },
      "accountApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your account-level API key in the `x-api-key` header. Agent keys are refused." }
    },
    "parameters": {
      "AuthorizationRequestId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The `authorizationRequestId` returned by `/api/v2/authorize`." }
    },
    "schemas": {
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } }, "additionalProperties": true },
      "OAuthError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "examples": ["invalid_client"] }, "error_description": { "type": "string" } } },
      "AuthorizeRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": { "type": "string", "minLength": 1, "maxLength": 128, "description": "What the agent wants to do. Required: a request without one is refused (400).", "examples": ["approve_claim"] },
          "resource": { "type": "object", "properties": { "id": { "type": "string", "description": "What it acts on. Defaults to `*` when omitted." }, "type": { "type": "string" } } },
          "context": { "type": "object", "additionalProperties": true, "description": "Facts about this request, such as an amount. At most 32 KB as JSON (413 above that) and 32 levels deep (400). Values that look like credentials or identifiers are not stored." },
          "endUserId": { "type": "string", "description": "The person the agent is acting for, when it acts for one." },
          "audience": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Optional. The downstream system a decision token should be issued for when the answer is allow." },
          "signals": { "type": "object", "properties": { "domain": { "type": "string" }, "industryContext": { "type": "string" }, "signal1": { "type": "string" }, "signal2": { "type": "string" } }, "description": "Optional context signals recorded with the decision." }
        }
      },
      "AuthorizeResponse": {
        "type": "object",
        "required": ["authorizationRequestId", "decision"],
        "properties": {
          "authorizationRequestId": { "type": "string" },
          "decision": { "type": "string", "enum": ["allow", "deny", "escalate"] },
          "reason": { "type": ["string", "null"] },
          "ruleMatched": { "type": "boolean" },
          "ruleName": { "type": "string" },
          "appliedScope": { "type": "object", "additionalProperties": true },
          "approvalRequestId": { "type": "string", "description": "Present when a person must decide." },
          "escalationReason": { "type": ["string", "null"] },
          "escalationTier": { "type": ["string", "null"] },
          "escalationSlaMinutes": { "type": ["number", "null"] },
          "endUserCanDecide": { "type": "boolean" },
          "autonomousApprovalReason": { "type": ["string", "null"] },
          "violationAction": { "type": "string", "description": "What an out-of-scope attempt did to the agent: revoked or flagged." },
          "contextRedactedPaths": { "type": "array", "items": { "type": "string" }, "description": "Context fields that were not stored because they looked like credentials or identifiers." },
          "signalQuality": { "type": "string", "enum": ["RULED", "RICH", "STANDARD", "DEGRADED", "MINIMUM"] },
          "overallConfidence": { "type": "number" },
          "utpCode": { "type": "string" },
          "witness": { "type": ["object", "null"], "additionalProperties": true },
          "decisionToken": { "type": "string" },
          "decisionTokenExpiresIn": { "type": "number" },
          "decisionTokenUnavailable": { "type": "string" },
          "latencyMs": { "type": "number" }
        },
        "additionalProperties": true
      },
      "DecisionTokenResponse": { "type": "object", "required": ["decisionToken", "expiresIn"], "properties": { "decisionToken": { "type": "string" }, "expiresIn": { "type": "number", "description": "Seconds until the token expires." } } },
      "TokenRequest": {
        "type": "object",
        "required": ["grant_type", "client_id", "client_secret"],
        "properties": {
          "grant_type": { "type": "string", "enum": ["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"] },
          "client_id": { "type": "string" },
          "client_secret": { "type": "string" },
          "scope": { "type": "string", "description": "Space-delimited list of actions, to narrow the token below the agent's full permissions." },
          "audience": { "type": "string", "minLength": 1, "maxLength": 255 },
          "end_user_id": { "type": "string", "description": "client_credentials only: bind the token to one end user's consent." },
          "subject_token": { "type": "string", "description": "Token exchange only: the signed-in user's token." },
          "subject_token_type": { "type": "string", "enum": ["urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:jwt"] }
        }
      },
      "TokenResponse": {
        "type": "object",
        "required": ["access_token", "token_type", "expires_in"],
        "properties": {
          "access_token": { "type": "string" },
          "token_type": { "type": "string", "enum": ["Bearer"] },
          "expires_in": { "type": "number" },
          "issued_token_type": { "type": "string", "description": "Token exchange only." },
          "scope": { "type": "string", "description": "Token exchange only." }
        }
      },
      "ConsentSessionRequest": {
        "type": "object",
        "required": ["agent_id", "customer_id", "scope"],
        "properties": {
          "agent_id": { "type": "string" },
          "customer_id": { "type": "string" },
          "scope": { "type": "array", "items": { "type": "string" }, "description": "The actions the person is asked to allow." },
          "excluded_scope": { "type": "array", "items": { "type": "string", "maxLength": 128 }, "maxItems": 50, "description": "Optional. Actions to show the person as \"It will not be able to\". Display only; none may also be in `scope`." },
          "end_user_id": { "type": "string", "description": "Which of your end users this is for. Omit when sending `subject_token`." },
          "identity_provider_id": { "type": "string", "description": "A registered identity provider id, with `end_user_id`." },
          "subject_token": { "type": "string", "description": "A JWT that identifies the user and the provider. Send it alone." },
          "expires_in": { "type": "number" },
          "require_auth": { "type": "boolean", "description": "Require your institution to confirm the person's sign-in before a grant." },
          "auth_redirect_url": { "type": "string", "format": "uri", "description": "Must be an https URL." }
        }
      }
    }
  }
}
