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/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 endpoints are org-scoped, but the organization is not named in the URL. It comes from the session token, so GET /skills returns the skills of whichever organization your session is currently bound to.

/skills          the current org's skills
/objects         the current org's objects
/captures        the current org's captures

A user may belong to several organizations, and a session is bound to one of them at a time. To act on a different one, exchange the session for a session in that org:

POST https://api.holos.io/users/exchange-session
Authorization: Bearer <session_jwt>

The endpoints that do name an organization in the path are the ones that administer it rather than work inside it, such as GET /organizations/{id}/members and POST /organizations/{id}/objects/upload. Authorization is enforced per-org from the member’s role in the bound organization.

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