# OkoSign quickstart

OkoSign makes qualified electronic signatures with Smart-ID. You prepare a document and the people who must sign, send it, and follow it until it is signed. The people you send it to need no account. Only the person whose account it is signs their own part, with PIN2 on their phone.

## Two ways in

- **An API key**, for your own scripts. The person creates it on okosign.com (Account, API keys) and the script sends it as `Authorization: Bearer oks_live_…`. A key reaches `https://app.okosign.com/v1` only. It is shown once; keep it like a password.
- **An assistant connection**, for AI assistants. The assistant connects to the MCP server at `https://app.okosign.com/mcp`; the person signs in to OkoSign in their browser and chooses what the assistant may do. The access token reaches `https://app.okosign.com/mcp` and `https://app.okosign.com/v1`. See [Rules for agents](https://app.okosign.com/docs/agents.md).

Either way the person must have confirmed who they are with Smart-ID on okosign.com once before anything can be sent. Until then the answer is `identity_required`, with the address where they do it.

## The API in one page

- Base address: `https://app.okosign.com/v1`. The OpenAPI document is at `https://app.okosign.com/openapi.json`.
- Bodies are JSON (`Content-Type: application/json`), at most 1 MB. A body may carry only the fields a route names: an unknown field is refused with `400 validation`.
- Every error is `{ "code": "…", "message": "…" }`, sometimes with more fields (`field` names what was wrong). Read the `code`.
- Requests are limited per key or connection; the `RateLimit` headers show where you are, and `429` means wait.
- Every answer is `Cache-Control: no-store`.

## Send a document

1. Make a PDF from text (or upload a file with `POST /v1/uploads`, raw bytes, `X-File-Name` naming it):

```
curl -s https://app.okosign.com/v1/documents/from-markdown \
  -H "Authorization: Bearer $OKOSIGN_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Lease","markdown":"# Lease\n\nThe parties agree…"}'
```

The answer has a `documentId`.

2. Prepare the request. Nothing is sent yet:

```
curl -s https://app.okosign.com/v1/requests \
  -H "Authorization: Bearer $OKOSIGN_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Lease","documents":[{"documentId":"upl_…"}],"recipients":[{"name":"Anna Berzina","email":"anna@example.com"}]}'
```

The answer is the request, with its `ref` (like `OKS-2026-0001`) and `status: "draft"`.

3. Look at what each person will receive: `POST /v1/requests/{ref}/preview`.

4. Send it: `POST /v1/requests/{ref}/send`. The answer is `{ "status": "sent", "request": … }`, or `202 { "status": "confirmation_required", "url": … }` when the person has to say yes first on okosign.com (always for an assistant that has not been allowed to send on its own).

5. Follow it: `GET /v1/requests/{ref}` (`status`, and each person's status), or receive a webhook (see [Rules for agents](https://app.okosign.com/docs/agents.md)).

6. Fetch the signed files when it is completed: `GET /v1/requests/{ref}/files` answers one-hour download links (`GET https://app.okosign.com/v1/files/<token>`, no header needed).

## Signing yourself

`POST /v1/requests/{ref}/sign` asks the person's own phone for their signature on a request they are a signer of. The answer is a 4-digit code (their phone shows the same code; they compare, then enter PIN2) or a link to the signing page. Add `"iSign": true` when creating the request to be the first signer.

## Limits

- Up to 10 documents a request, 25 MB each and 40 MB together; up to 20 people.
- Markdown to PDF: at most 200,000 characters and 100 pages.

More: [File formats](https://app.okosign.com/docs/formats.md), [Pricing](https://app.okosign.com/docs/pricing.md).