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

# Authentication

> How to authenticate with the Uplint API using API keys and JWT tokens.

All Uplint API requests require authentication via the `Authorization` header. Uplint supports two authentication methods: **API keys** (for programmatic access) and **JWT tokens** (for dashboard sessions).

## API keys

API keys are the primary way to authenticate with the Uplint API. Each key is scoped to a specific set of permissions and is bound to a tenant.

### Format

API keys follow the format `ul_live_` followed by a random string:

```
ul_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

### Usage

Pass the key in the `Authorization` header:

```bash theme={null}
# With Bearer prefix (recommended)
curl -H "Authorization: Bearer ul_live_a1b2c3d4..." https://api.uplint.dev/api/v1/files

# Without prefix (also accepted)
curl -H "Authorization: ul_live_a1b2c3d4..." https://api.uplint.dev/api/v1/files
```

### Scopes

Each API key carries one or more permission scopes:

| Scope      | Description                                                           |
| ---------- | --------------------------------------------------------------------- |
| `upload`   | Upload files to any context                                           |
| `download` | Generate download URLs for files                                      |
| `metadata` | Read file metadata and list files                                     |
| `delete`   | Delete files                                                          |
| `admin`    | Full access — includes all scopes plus API key and context management |

When creating a key, assign only the scopes it needs. A backend service that uploads and reads files only needs `upload`, `download`, and `metadata`.

### Key lifecycle

API keys have three states:

* **Active** — The key works normally.
* **Disabled** — The key is temporarily deactivated. It can be re-enabled at any time.
* **Revoked** — The key is permanently deactivated. This action is irreversible.

### Expiration

Keys can be created with an expiration date (1–365 days) or without one. Expired keys are automatically treated as revoked.

### Security best practices

* **Store keys securely.** The full key is only returned once at creation time. Use a secrets manager or environment variables — never commit keys to source code.
* **Use least-privilege scopes.** Only grant the permissions each key needs.
* **Rotate keys regularly.** Create new keys and revoke old ones on a schedule.
* **Set expiration dates.** For time-limited integrations, set `expires_in_days` at creation.
* **Monitor usage.** Check `last_used_at` in key details to detect unused or compromised keys.

## JWT tokens

JWT tokens are used by the Uplint dashboard and are issued during login. They carry the user's identity and tenant context.

For programmatic access, use API keys instead of JWT tokens.

## Error responses

Authentication failures return a `401` status:

```json theme={null}
{
  "status": "ERROR",
  "message": "Invalid or missing API key",
  "errors": ["Authentication required"],
  "timestamp": "2026-02-10T12:00:00Z"
}
```

Common causes:

* Missing `Authorization` header
* Expired API key
* Disabled or revoked API key
* Key doesn't have the required scope for the endpoint