Skip to main content
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

RolePermissions
ownerFull access including org settings
adminFull access excluding ownership transfer
managerCan create and edit skills, captures, and objects
memberCan view and record captures