Introdução - UserKit

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:

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.

A organização ativa

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

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

202 não é “na fila”. Em forgot-password, no magic link e no código por e-mail ele significa “aceito, e a resposta seria a mesma de qualquer jeito” — a API não revela se um endereço tem conta.

Erros são sempre o mesmo envelope:

{ "error": { "code": "forbidden", "message": "your role does not allow this action" } }

Ramifique em code. Veja Erros.

Timestamps

RFC 3339, UTC:

{ "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:

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.

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.

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.

Rate limits

Endpoints públicos e de credencial são limitados por IP; o boot é adicionalmente limitado por chave publicável. A superfície de máquina é limitada por chave de API — 1000 por minuto, 3000 entre as chaves de um ambiente — e reporta onde você está em headers RateLimit-* em toda resposta, não só na recusa. Veja Rate limits.

Repetindo uma escrita

Toda escrita na superfície de máquina aceita o header Idempotency-Key. Envie um e a repetição recebe a mesma resposta de volta — mesmo status, mesmo corpo, Idempotent-Replay: true — em vez de executar duas vezes.

curl -s $API/v1/contacts \
  -H "Authorization: Bearer uk_sk_…" \
  -H "Idempotency-Key: 2f1c8a3e-9b40-4c2d-8f11-6a7e0d5b2c94" \
  -H 'Content-Type: application/json' \
  -d '{ "external_id": "user_8421",
       "customer": { "external_id": "org_77", "name": "Acme" } }'

Veja Idempotência.

As superfícies

Plano de staff

uk_st_…. Login, conta, organizações, membros, papéis, chaves, e a visão do painel sobre contatos.

Superfície de máquina

uk_sk_…. /v1/me e /v1/contacts — o seu backend falando sobre os seus próprios usuários.

Plano de clientes

Chave publicável no corpo. /v1/boot e /v1/contact-auth/*, chamados das suas páginas.

Superfície de contato

uk_ct_…. /v1/contact/me — um dos seus usuários lendo o próprio registro.

​Requisições

​A organização ativa

​Respostas

​Timestamps

​Identificadores

​Paginação

​Ambientes

​Rate limits

​Repetindo uma escrita

​As superfícies

Plano de staff

Superfície de máquina

Plano de clientes

Superfície de contato

Requisições

A organização ativa

Respostas

Timestamps

Identificadores

Paginação

Ambientes

Rate limits

Repetindo uma escrita

As superfícies