> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attesso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Review the Attesso v1 resources, endpoints, and execution contract.

The Attesso API is a server-to-server JSON interface for mandates, authorizations, and signed evidence.

## Base URLs

| Environment | Base URL                          | Key prefix     |
| ----------- | --------------------------------- | -------------- |
| Staging     | `https://api-staging.attesso.com` | `att_test_...` |
| Production  | `https://api.attesso.com`         | `att_live_...` |

Use an environment-matching key. Resources and credentials do not cross environments.

## Resources and endpoints

| Method | Path                                                 | Purpose                                  |
| ------ | ---------------------------------------------------- | ---------------------------------------- |
| `POST` | `/v1/mandates`                                       | Create an immutable mandate              |
| `GET`  | `/v1/mandates/{mandate_id}`                          | Retrieve current mandate state           |
| `POST` | `/v1/mandates/{mandate_id}/approval-sessions`        | Create a hosted approval session         |
| `PUT`  | `/v1/mandates/{mandate_id}/revocation`               | Revoke an unconsumed mandate             |
| `POST` | `/v1/mandates/{mandate_id}/authorizations`           | Evaluate and reserve one proposed action |
| `GET`  | `/v1/authorizations/{authorization_id}`              | Retrieve current authorization state     |
| `PUT`  | `/v1/authorizations/{authorization_id}/commit`       | Confirm executor acceptance              |
| `PUT`  | `/v1/authorizations/{authorization_id}/cancellation` | Release an action that cannot execute    |
| `GET`  | `/v1/mandates/{mandate_id}/evidence`                 | Retrieve portable signed evidence        |
| `GET`  | `/.well-known/jwks.json`                             | Retrieve evidence verification keys      |

The `/browser/v1/...` routes used by the hosted approval page are private to Attesso's isolated approval origin. Do not call them from your integration.

## Media types

* Requests and ordinary responses use `application/json`.
* Errors use `application/problem+json` when Attesso supplies a body.
* Signed evidence uses `application/jose+json`.

## Execution contract

<Warning>
  An HTTP success response is not permission to execute. Your backend may continue only when the latest authorization representation has `can_execute: true`.
</Warning>

`ALLOW`, `RESERVED`, and `execute_before` explain the grant, but `can_execute` is the final gate after deadline reconciliation.

## Response headers

* `Attesso-Request-Id` is safe to log and use for support correlation.
* `Idempotency-Replayed: true` indicates an earlier write was replayed.
* `Location` identifies a newly created resource where supplied.
* `Retry-After` may accompany a retryable `503` response.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key-round" href="/reference/authentication">
    Store keys safely and isolate staging from production.
  </Card>

  <Card title="Errors and idempotency" icon="rotate-ccw" href="/reference/errors-and-idempotency">
    Fail closed and make retries safe.
  </Card>
</CardGroup>