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

# Introdução

> URL base, content types, paginação e o formato de toda resposta.

Uma API HTTP, versionada em `/v1`, JSON na entrada e JSON na saída.

```
https://api.userkit.dev/v1
```

Os exemplos deste guia usam `$API` para essa base. O playground de cada página de
endpoint já aponta para lá.

## Requisições

`Content-Type: application/json` em qualquer coisa com corpo. Os corpos têm teto de
1 MiB; um corpo grande demais falha no leitor em vez de ser bufferizado em memória
antes.

Credenciais viajam em `Authorization: Bearer`:

```bash theme={null}
curl -s $API/v1/session -H "Authorization: Bearer uk_st_…"
```

Nada mais é aceito. Nenhum parâmetro de query — cairia em logs de acesso e no
histórico do navegador. Nenhum cookie — esta API não é autenticada por cookie, e é
também por isso que o CORS nunca precisa de credenciais.

A exceção é a chave publicável, que viaja no **corpo** dos endpoints que a aceitam,
ao lado dos dados de que esses endpoints já precisam.

Veja [Autenticação](/pt-br/api-reference/authentication).

## A organização ativa

Rotas autenticadas por sessão agem sobre uma organização. Qual delas vem de um
header:

```bash theme={null}
curl -s $API/v1/organization/members \
  -H "Authorization: Bearer uk_st_…" \
  -H "X-Organization-Id: org_4b1e…"
```

Ele **identifica**; não autoriza. O JOIN do vínculo é o que autoriza, então um
código do qual você não é membro não resolve nada. Omitido, responde a organização
padrão da sessão.

## Respostas

Sucesso é um `2xx` com corpo JSON, exceto `204`, que não tem nenhum.

| Status | Usado para                                   |
| ------ | -------------------------------------------- |
| `200`  | Leitura, ou escrita que devolve estado       |
| `201`  | Algo foi criado                              |
| `202`  | Aceito — e deliberadamente não diz mais nada |
| `204`  | Feito, nada a dizer                          |

<Note>
  `202` não é "na fila". Em `forgot-password`, `signup` e nos fluxos de magic link ele
  significa "aceito, e a resposta seria a mesma de qualquer jeito" — a API não revela
  se um endereço tem conta.
</Note>

Erros são sempre o mesmo envelope:

```json theme={null}
{ "error": { "code": "forbidden", "message": "your role does not allow this action" } }
```

Ramifique em `code`. Veja [Erros](/pt-br/api-reference/errors).

## Timestamps

RFC 3339, UTC:

```json theme={null}
{ "created_at": "2026-07-29T12:00:00Z" }
```

Um timestamp anulável vem como `null`, nunca como string vazia ou data zero.

## Identificadores

UUIDs, com duas exceções:

* **código público da organização** — `org_<32 hex>`, o que vai nas URLs e no header
  `X-Organization-Id`;
* **prefixos de credencial** — `uk_sk_`, `uk_pk_`, `uk_st_`, `uk_ct_`, e as famílias
  de token de uso único.

O UUID interno da organização nunca sai da API nas superfícies que o painel usa.

## Paginação

Leituras de coleção aceitam `limit` e `offset`:

```bash theme={null}
curl -s "$API/v1/contacts?limit=100&offset=200" \
  -H "Authorization: Bearer uk_sk_…"
```

|          |                                                  |
| -------- | ------------------------------------------------ |
| `limit`  | Padrão 50, máximo 200. Fora disso volta para 50. |
| `offset` | Padrão 0.                                        |

O teto é deliberado: suficiente para uma tela, pequeno o bastante para ninguém baixar
a audiência inteira sem querer.

<Note>
  Valores fora da faixa **não** são erro — eles voltam para o padrão. Não conte com um
  `400` para pegar um tamanho de página inválido.
</Note>

## Ambientes

Na superfície de máquina, o ambiente é o da chave, resolvido a partir da linha
armazenada em toda requisição. Não existe parâmetro para ele.

Na superfície do painel, as leituras aceitam `?environment=live|test`, com padrão
`live`.

Os dois estão cobertos em [Ambientes](/pt-br/concepts/environments).

## Rate limits

Endpoints públicos e de credencial são limitados por IP; o boot é adicionalmente
limitado por chave publicável. Veja
[Rate limits](/pt-br/api-reference/rate-limits).

## As superfícies

<CardGroup cols={2}>
  <Card title="Plano de staff" icon="user">
    `uk_st_…`. Login, conta, organizações, membros, papéis, chaves, e a visão do
    painel sobre contatos.
  </Card>

  <Card title="Superfície de máquina" icon="server">
    `uk_sk_…`. `/v1/me` e `/v1/contacts` — o seu backend falando sobre os seus
    próprios usuários.
  </Card>

  <Card title="Plano de clientes" icon="globe">
    Chave publicável no corpo. `/v1/boot` e `/v1/contact-auth/*`, chamados das suas
    páginas.
  </Card>

  <Card title="Superfície de contato" icon="user-check">
    `uk_ct_…`. `/v1/contact/me` — um dos seus usuários lendo o próprio registro.
  </Card>
</CardGroup>