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

# Identidade e usuários

> O modelo User da Cativa e o endpoint canônico para validar credenciais.

Toda integração com a Cativa começa pelo usuário. Esta página descreve o modelo `User` no nível conceitual e o endpoint canônico para validar credenciais.

## O modelo User

Cada usuário na Cativa pertence a **um único tenant** e é identificado por um `id` (GUID). Os campos visíveis em respostas autenticadas incluem identidade básica (`email`, `firstName`, `lastName`, `displayName`, `userName`), URL pública da foto (`pictureUrl`), o `role` na comunidade, status da conta e o `customer` (tenant) ao qual o usuário pertence.

<Note>
  O contrato detalhado de cada response (incluindo nomes e tipos exatos de cada campo) será publicado em breve por endpoint, junto com o catálogo público da API.
</Note>

## Validar credencial e descobrir o usuário associado

O único endpoint canônico para parceiros validarem uma credencial e descobrirem o usuário associado é `GET /social/v1/auth/me`:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://apis.cativalab.digital/tenant/v1/auth/me \
    -H "Authorization: Bearer cativa_live_..."
  ```

  ```js Node theme={null}
  const res = await fetch('https://apis.cativalab.digital/tenant/v1/auth/me', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  const me = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      'https://apis.cativalab.digital/tenant/v1/auth/me',
      headers={
          'Authorization': f'Bearer {api_key}'
      }
  )
  me = res.json()
  ```
</CodeGroup>

Use o retorno para:

* Confirmar que sua chave está válida e aponta pro tenant certo (campo `customer`).
* Capturar o `id` do usuário associado à chave (útil pra logs e auditoria do seu lado).
* Renovar a sessão usando os campos `accessToken` / `refreshToken` retornados.

## Padrão de upsert por usuário externo

<Note>
  Endpoints de `POST/PATCH/DELETE /users` para parceiros externos (sincronização CRM, criação de usuário a partir de compra externa, soft-delete) serão publicados em breve. Por enquanto, alinhe com o time da Cativa via [dev@cativa.digital](mailto:dev@cativa.digital) para discutir o fluxo do seu caso.
</Note>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Badges como permissão" icon="shield-check" href="/pt-BR/concepts/badges-as-permissions">
    Como atribuir credenciais a um usuário para liberar acesso a grupos e cursos.
  </Card>

  <Card title="Comunidades e Espaços" icon="layer-group" href="/pt-BR/concepts/communities-and-spaces">
    Onde o usuário se encaixa na hierarquia de Comunidade > Espaço > Grupo.
  </Card>
</CardGroup>