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

# Authentication

> How to obtain and use session tokens with the Holos API.

The Holos API uses token-based authentication. Every request must include a session token in the `Authorization` header. Tokens are obtained through a passwordless magic link flow.

## Obtaining a token

Authentication is a three-step flow:

**1. Request a magic link**

```http theme={null}
POST https://api.holos.io/users/send-magic-link
Content-Type: application/json

{
  "email_address": "you@example.com"
}
```

**2. Authenticate the token from the link**

The user receives an email containing a magic link. Extract the token from the link and exchange it:

```http theme={null}
POST https://api.holos.io/users/authenticate-magic-link
Content-Type: application/json

{
  "token": "<token_from_magic_link>"
}
```

This returns an `intermediate_session_token` along with a list of organizations the user belongs to.

**3. Exchange for an org-scoped session**

```http theme={null}
POST https://api.holos.io/users/exchange-session
Content-Type: application/json

{
  "intermediate_session_token": "<token_from_step_2>",
  "organization_id": "<org_id>"
}
```

The response contains a `session.jwt`. This is the token you'll use for all subsequent requests.

## Making authenticated requests

Pass the session JWT as a bearer token:

```http theme={null}
GET https://api.holos.io/api/org/:orgId/skills
Authorization: Bearer <session_jwt>
```

Requests without a valid token receive a `401 Unauthorized` response.

## Token expiry

Session tokens expire after a configurable period. When a token expires, re-authenticate using the magic link flow above. The Holos dashboard and apps handle refresh automatically.

## Organization context

Most API endpoints are scoped to an organization, identified by its slug or ID in the URL path:

```
/api/org/:orgId/...
```

A user may belong to multiple organizations. The session token is valid across all orgs the user is a member of, but authorization is enforced per-org based on the user's role.

## Roles

| Role      | Permissions                                       |
| --------- | ------------------------------------------------- |
| `owner`   | Full access including org settings                |
| `admin`   | Full access excluding ownership transfer          |
| `manager` | Can create and edit skills, captures, and objects |
| `member`  | Can view and record captures                      |