Authentication

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

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:

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

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:

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

Overview

Concepts

Resources

Obtaining a token

Making authenticated requests

Token expiry

Organization context

Roles

​Obtaining a token

​Making authenticated requests

​Token expiry

​Organization context

​Roles

Obtaining a token

Making authenticated requests

Token expiry

Organization context

Roles