> ## 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.

# Primeiros passos

> De uma conta nova ao seu primeiro contato identificado, numa sentada só.

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`.

```bash theme={null}
export API="https://api.userkit.dev"
```

## 1. Crie sua conta

Cadastre-se em [app.userkit.dev](https://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.

<Note>
  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.
</Note>

## 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_…`).

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

```bash theme={null}
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.

```bash theme={null}
curl -s $API/v1/me -H "Authorization: Bearer $UK_KEY"
```

```json Resposta theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

```json Resposta — 201 theme={null}
{
  "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.

<Note>
  `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.
</Note>

## 5. Leia de volta

```bash theme={null}
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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Contatos" icon="users" href="/pt-br/concepts/contacts">
    Arestas de identidade, atribuição e como os merges funcionam.
  </Card>

  <Card title="Escolhendo o modo de auth" icon="route" href="/pt-br/customer-auth/modes">
    Hosted ou federado — decida antes de ligar o front.
  </Card>

  <Card title="Ambientes" icon="layer-group" href="/pt-br/concepts/environments">
    O que live e test realmente separam.
  </Card>

  <Card title="Papéis e permissões" icon="shield-halved" href="/pt-br/concepts/roles-and-permissions">
    Dê ao seu time menos do que tudo.
  </Card>
</CardGroup>