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

# Authentication

> API keys for data-plane access and JWTs for portal management endpoints.

# Authentication

Remem uses two auth models:

* **API keys (`vlt_...`)** for data-plane endpoints (`/v1/query`, `/v1/documents/*`, `/v1/dsar/*`).
* **Portal JWT bearer tokens** for management endpoints (`/v1/orgs/*`, `/v1/tenants/*`, `/v1/auth/*`, `/v1/namespaces/*`).

## Data Plane: API Keys

Use either header format:

```bash theme={null}
curl -X POST https://api.remem.io/v1/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: vlt_..." \
  -d '{"query":"latest notes"}'
```

```bash theme={null}
curl -X POST https://api.remem.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vlt_..." \
  -d '{"query":"latest notes"}'
```

### How to get an API key

1. **Fastest path:** `POST /public/signup` returns your first API key.
2. **Additional keys:** create/revoke via `/v1/auth/api-keys` using a portal JWT.

### API key sensitivity scope

Each key has a max sensitivity level:

| Level          | Can read                         |
| -------------- | -------------------------------- |
| `public`       | Public only                      |
| `internal`     | Public + internal                |
| `confidential` | Public + internal + confidential |
| `personal`     | All levels                       |

Query filters are automatically intersected with the key's max scope.

### API key namespace scope

API keys are also namespace-scoped.

* Each key can have a **default namespace** for write calls that omit `namespace`.
* Each key can have per-namespace grants:
  * `read_write`
  * `read_only`
* Reads without an explicit `namespaces` field search **all namespaces the key can read**.

Example management payload:

```bash theme={null}
curl -X POST https://api.remem.io/v1/auth/api-keys \
  -H "Authorization: Bearer <portal_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "<workspace_uuid>",
    "name": "research-agent",
    "default_namespace_id": "<research_namespace_uuid>",
    "scopes": [
      {
        "namespace_id": "<research_namespace_uuid>",
        "permissions": ["read", "write"]
      },
      {
        "namespace_id": "<shared_namespace_uuid>",
        "permissions": ["read"]
      }
    ]
  }'
```

<Note>
  If you omit `scopes` on key creation, Remem grants `read_write` on the workspace's `default` namespace. See [Namespaces](/namespaces) for the full model.
</Note>

## Management Plane: Portal JWT

Management endpoints require **non-API-key bearer JWTs**.

Examples:

* `/v1/orgs/*`
* `/v1/orgs/{org_id}/members/*`
* `/v1/orgs/{org_id}/invites/*`
* `/v1/tenants/*`
* `/v1/tenants/{tenant_id}/members/*`
* `/v1/auth/api-keys*`
* `/v1/namespaces/*`
* `/v1/auth/password-reset/*` (public reset flow endpoints themselves are unauthenticated)

Example:

```bash theme={null}
curl -X GET https://api.remem.io/v1/tenants/ \
  -H "Authorization: Bearer <portal_jwt>"
```

## Public Endpoints (No Auth)

* `GET /`
* `GET /health`
* `GET /health/live`
* `GET /health/ready`
* `GET /health/services`
* `POST /public/signup`
* `POST /v1/auth/password-reset/request`
* `POST /v1/auth/password-reset/confirm`

## Common 401 Errors

* `API key required...`: you called a data-plane endpoint without `vlt_` key.
* `Portal JWT required...`: you called a management endpoint with an API key.
* `Invalid JWT`: malformed/expired portal token.
* `Invalid API key`: revoked or incorrect `vlt_` token.