# Developer Guide overview

Everything an engineer needs to integrate a trading system, automation, or AI agent.

## Base URL and version prefix

The vault exposes a single REST API versioned by URL prefix. All resource endpoints live under `/v1/`. The base URL depends on your deployment and is not embedded in the spec. Your deployment docs provide the correct value. Browse the full [API Reference](/api-reference) for every endpoint.

```
https://<your-vault-host>/v1/<resource>
```

Three paths are available at the root with no version prefix: `/health`, `/openapi.json`, and `/openapi.yaml` (see the [common endpoints](/api-reference#tag/common)). Use `GET /v1/info` to retrieve the current API version string and the RSA public key used for key import.

## Request and response conventions

All requests and responses use `application/json`. Set `Content-Type: application/json` on every request that includes a body.

Successful responses return `200 OK` with a JSON payload. The one exception is the backup export (`GET /v1/keys-backup`), which returns an `application/zip` archive.

Most mutation endpoints are **asynchronous**. They return either:

* `200 OK` with the completed resource if the operation finished synchronously.
* `202 Accepted` with `{"status": "processing", "request_id": "<string>"}` if it was queued.

[Poll the request](/api-reference#tag/requests) with `GET /v1/requests/{request_id}` until the status is no longer `"processing"`. The completed response is a tagged union containing the operation result.

Signing (`POST /v1/keys/{key_id}/sign`, see the [Keys API](/api-reference#tag/keys)) is always synchronous and returns `200` with `{"signature": "<string>"}` directly.

## Caller-supplied IDs

All `POST` endpoints that create resources accept a caller-supplied `id` field. You choose the ID; the vault stores it as the primary identifier. Pick IDs that are stable and meaningful in your system (for example, `"binance-trading-bot"` or `"eth-mainnet-signer"`). IDs must be unique within their resource type.

## Who uses which authentication path

There are two identity types in the vault:

| Identity type | Auth token | Request assertion |
|---|---|---|
| Machine Users and Agents | `ApiKey <uuid>` in `Authorization` header | Ed25519 signature over a SHA-256 transcript |
| Human users | `Bearer <jwt>` in `Authorization` header | WebAuthn passkey assertion |

Machine users and AI agents use the Ed25519 path. This is the right choice for automated systems, trading bots, and any code that runs without human interaction. The UUID API key identifies the caller; the Ed25519 signature proves the request was not tampered with.

Human users authenticate with a JWT from your cloud identity provider (Google) and prove sensitive operations with a WebAuthn passkey. Most integrations do not use this path.

See the [Request signing model](/develop/authentication/overview) for the header layout and the [Machine Users and Agents](/develop/authentication/machine-users) page for the full transcript construction.

## Common integration tasks

| Task | Where to look |
|---|---|
| Authenticate as a machine user or agent | [Machine Users and Agents](/develop/authentication/machine-users) |
| Generate or import a key | [Import and generate keys](/develop/keys-api) |
| Sign a message | [Raw signing](/develop/signing/raw-sign) |
| Understand signing request states | [Signing request lifecycle](/develop/signing/request-lifecycle) |
| Freeze or unfreeze a key | [Freeze and unfreeze](/develop/freeze) |
| Export an encrypted backup | [Export a backup](/develop/backup-export) |
| Pull audit events | [Export the audit log](/develop/audit-export) |
| Error codes and pagination | [Errors, pagination and idempotency](/develop/conventions/errors-pagination) |
| Connect an AI agent directly | [Connect an AI agent](/develop/connect-ai-agent) |

## Quick reference: read-only endpoints that skip request signing

Some read-only endpoints accept only the `Authorization` header and do not require the nonce, timestamp, or assertion headers:

* `GET /v1/admin-policies`: see [Admin Policies](/api-reference#tag/adminpolicies)
* `GET /v1/audit-logs`: see [Audit Logs](/api-reference#tag/auditlogs)
* `GET /v1/whoami`: see [Whoami](/api-reference#tag/whoami)
* `GET /v1/requests/{request_id}`: see [Requests](/api-reference#tag/requests)

The info endpoints (`GET /v1/info`, `GET /v1/system-info`), the health check (`GET /health`), and the spec endpoints (`/openapi.json`, `/openapi.yaml`) require no auth at all (see [Common](/api-reference#tag/common) and [Docs](/api-reference#tag/docs)).

Every other endpoint requires all four auth headers. See the [Request signing model](/develop/authentication/overview) for details.