# unauthorized

<Badge variant="warning">401 Unauthorized</Badge> <Badge variant="muted">unauthorized</Badge>

| Field           | Value                                         |
|-----------------|-----------------------------------------------|
| **Type URI**    | `https://docs.kordiam.app/docs/errors/unauthorized` |
| **HTTP Status** | `401 Unauthorized`                            |

## Description

The request lacks valid authentication credentials or the provided credentials are invalid. Returned both for protected endpoints when the bearer token is missing/invalid/expired and for the bootstrap endpoints (`/api/v2/auth/token`, `/api/v2/auth/refresh`) when the supplied client credentials or refresh token are rejected.

## Response Example

```json
{
  "type": "https://docs.kordiam.app/docs/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired authentication token",
  "instance": "/api/v2/elements",
  "traceId": "abc-123-def"
}
```

The `detail` value depends on the failure mode:

| Scenario                                                              | `detail`                              |
|-----------------------------------------------------------------------|---------------------------------------|
| Missing/expired/malformed bearer token on a protected endpoint        | `Invalid or expired authentication token` |
| Wrong `client_id` / `client_secret` on `/api/v2/auth/token`           | `Invalid client credentials`          |
| Refresh token unknown or expired on `/api/v2/auth/refresh`            | `Invalid or expired refresh token`    |

## Common Causes

- Missing the `Authorization` header entirely on a protected endpoint
- Using an expired or malformed access token
- Submitting wrong `client_id` / `client_secret` to `/api/v2/auth/token`
- Using a refresh token that is unknown, expired, or already rotated

## How to Fix

Obtain a valid access token through the [authentication flow](/docs/getting-started/authentication) and include it in the `Authorization` header as a bearer token. For example:

```
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
```

If your token has expired, request a new one via `/api/v2/auth/refresh` or by re-authenticating with `/api/v2/auth/token`. If credentials themselves are rejected, double-check the `client_id` / `client_secret` issued for your integration.