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

# Identity and Users

> Cativa's User model and the canonical endpoint to validate credentials.

Every integration with Cativa starts with the user. This page describes the `User` model at the conceptual level and the canonical endpoint for credential validation.

## The User model

Each Cativa user belongs to **exactly one tenant** and is identified by an `id` (GUID). Fields visible in authenticated responses include basic identity (`email`, `firstName`, `lastName`, `displayName`, `userName`), the public picture URL (`pictureUrl`), the community `role`, account status and the `customer` (tenant) the user belongs to.

<Note>
  The detailed contract for each response (including exact field names and types) will be published per-endpoint along with the public API catalog **soon**.
</Note>

## Validate credentials and discover the associated user

The single canonical endpoint for partners to validate a credential and discover the associated user is `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 the response to:

* Confirm your key is valid and points to the right tenant (the `customer` field).
* Capture the `id` of the user tied to the key (useful for your own logs and audit).
* Refresh the session via the returned `accessToken` / `refreshToken`.

## Upsert pattern from an external user

<Note>
  Public `POST/PATCH/DELETE /users` endpoints for external partners (CRM sync, creating a user from an external purchase, soft-delete) are **coming soon**. Until then, align with the Cativa team at [dev@cativa.digital](mailto:dev@cativa.digital) to discuss the flow for your specific case.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Badges as Permissions" icon="shield-check" href="/en/concepts/badges-as-permissions">
    How to assign credentials to a user to grant access to groups and courses.
  </Card>

  <Card title="Communities and Spaces" icon="layer-group" href="/en/concepts/communities-and-spaces">
    Where the user fits in the Community > Space > Group hierarchy.
  </Card>
</CardGroup>