Primeiros passos

Este guia percorre o caminho inteiro uma vez: criar a conta, pegar uma chave, identificar um contato e lê-lo de volta. Tudo abaixo roda contra https://api.userkit.dev.

export API="https://api.userkit.dev"

1. Crie sua conta

Cadastre-se em app.userkit.dev. O cadastro cria o usuário, a organização, o seu vínculo de owner, os dois ambientes e suas chaves publicáveis numa única transação, e já te deixa dentro do painel.

Toda organização nasce com um ambiente live e um test. O que separa os dois é a chave que você apresenta, nunca um parâmetro — comece pelo test e nada do que você fizer aqui aparece nos números de produção.

2. Gere uma chave de API

No painel, Configurações → Chaves de API, crie uma chave no ambiente test. Uma chave nasce dentro de um ambiente e nunca sai dele; o ambiente fica gravado no próprio prefixo (uk_sk_test_…).

O valor da chave aparece exatamente uma vez. Só o hash SHA-256 é armazenado, então uma chave perdida é substituída, nunca recuperada.

export UK_KEY="uk_sk_test_a91c…"

3. Confira a chave

A primeira chamada que todo integrador faz. O que volta é o ambiente ao qual a chave pertence — nada que você envie pode nomear outro.

curl -s $API/v1/me -H "Authorization: Bearer $UK_KEY"

Resposta

{
  "organization": { "id": "…", "name": "Analytical Engine" },
  "environment": { "id": "…", "kind": "test" },
  "api_key": { "id": "…", "prefix": "uk_sk_test_a91c" }
}

4. Identifique um contato

Agora o plano de clientes. Envie as identidades que o seu backend conhecer; pelo menos uma entre external_id, email ou anonymous_id é obrigatória.

curl -s $API/v1/contacts \
  -H "Authorization: Bearer $UK_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "external_id": "user_8421",
    "email": "grace@example.com",
    "name": "Grace Hopper"
  }'

Resposta — 201

{
  "contact": {
    "id": "3f9a…",
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "identified": true,
    "email_verified": false,
    "attribution": { "utm_source": null, "...": null },
    "first_seen_at": "2026-07-29T12:00:00Z"
  },
  "created": true
}

Chame de novo com o mesmo external_id e você recebe 200 com "created": false — identify é cria-ou-atualiza, não cria.

email_verified continua false até um link de verdade ser clicado. Passar um e-mail para a API registra um atributo; não comprova um.

5. Leia de volta

curl -s $API/v1/contacts/3f9a… -H "Authorization: Bearer $UK_KEY"

A leitura detalhada acrescenta as arestas de identidade do contato — os valores que resolvem até ele:

{
  "contact": {
    "id": "3f9a…",
    "identities": [
      { "kind": "external_id", "value": "user_8421", "created_at": "…" },
      { "kind": "email", "value": "grace@example.com", "created_at": "…" }
    ],
    "...": "..."
  }
}

Tente o mesmo id com uma chave live e você recebe 404. É o isolamento de ambiente funcionando: o ambiente da chave delimita a leitura, e o 404 não revela se a linha existe em outro lugar.

Para onde ir agora

Contatos

Arestas de identidade, atribuição e como os merges funcionam.

Escolhendo o modo de auth

Hosted ou federado — decida antes de ligar o front.

Ambientes

O que live e test realmente separam.

Papéis e permissões

Dê ao seu time menos do que tudo.

Comece por aqui

Conceitos

Autenticação de contatos

Guias

Primeiros passos

1. Crie sua conta

2. Gere uma chave de API

3. Confira a chave

4. Identifique um contato

5. Leia de volta

Para onde ir agora

Contatos

Escolhendo o modo de auth

Ambientes

Papéis e permissões

​1. Crie sua conta

​2. Gere uma chave de API

​3. Confira a chave

​4. Identifique um contato

​5. Leia de volta

​Para onde ir agora

Contatos

Escolhendo o modo de auth

Ambientes

Papéis e permissões

1. Crie sua conta

2. Gere uma chave de API

3. Confira a chave

4. Identifique um contato

5. Leia de volta

Para onde ir agora