API

The Halo console and account portal are built entirely on the JSON API described here, so anything they do, you can do with a script.

The reference is the OpenAPI 3.1 document at /api/v1/openapi.yaml on your Halo server, for example https://auth.example.com/api/v1/openapi.yaml, and in the repository at api/openapi.yaml. It lists every route with its roles, request and response schemas, and the error codes it returns. The console links to it under SDKs and reference. This page explains what the routes have in common.

Base URL

https://auth.example.com/api/v1

The web interface forwards /api to the Go server, so use Halo's public address. Inside your own network you can also call the Go server directly on HALO_LISTEN, for example http://halo-server:8080/api/v1 in the Docker Compose deployment.

Authentication

The API accepts three kinds of credentials.

Session cookie

The halo_session cookie is the one the browser gets when a person signs in. To call the API as yourself from a script:

1. Sign in to Halo in your browser.

2. Copy the value of the halo_session cookie from the browser's developer tools. The cookie is HttpOnly, so scripts on the page cannot read it.

3. Send it with every request:

   Bash

   curl https://auth.example.com/api/v1/me -H "Cookie: halo_session=$HALO_SESSION"
   

The session lasts as long as the session lifetime, 12 hours by default, and signing out ends it. In development, halo dev-session --email you@example.com prints a session for any user (it requires HALO_DEV=1).

API keys

Automation uses API keys of service accounts. Send the key as a bearer token:

curl https://auth.example.com/api/v1/users -H "Authorization: Bearer hlk_…"

• A key works on /api only when it has the api scope, and requests made with it have the roles of its service account.
• Keys are ignored on the personal routes under /api/v1/me and on the sign-in routes under /api/v1/auth, which act on a signed-in person.
• Halo stores only a hash of each key. A key stops working when it is revoked, when it expires, or when its service account is disabled.

Halo CLI access tokens

The personal routes under /api/v1/me/ also accept the access token that halo login obtained, as a bearer token. halo ssh-cert uses this to request certificates. GET /api/v1/me itself requires a session.

Roles

What a request may do depends on the roles of the person or service account behind it; see Concepts. Each operation in the OpenAPI document states the roles it requires. Requests without valid credentials get 401 with ERR_UNAUTHENTICATED, and requests your roles do not allow get 403 with ERR_FORBIDDEN.

Same-origin rule

Requests that change something (any method other than GET, HEAD and OPTIONS) must not come from another website. Halo blocks them with 403 and ERR_CROSS_SITE when the browser marks them as cross-site with Sec-Fetch-Site, or when their Origin header names an origin other than HALO_PUBLIC_URL. Command-line tools such as curl send neither header and pass. The security model has the exact rule.

Requests and responses

• Request and response bodies are JSON with camelCase field names. Send Content-Type: application/json.
• Request bodies may be at most 1 MiB. Halo rejects invalid JSON and fields it does not recognise with 400 and ERR_INVALID_JSON.
• PATCH routes change only the fields you send. PUT routes replace the whole object or list; send every field.
• Times are RFC 3339 strings, such as 2026-10-04T10:00:10Z.
• Ids are a prefix and a 26-character ULID, such as usr_01J9Z8Q4M2N5P7R9T1V3X5Z7B9. Common prefixes: usr_ users and service accounts, grp_ groups, app_ applications, crd_ client secrets, ses_ sessions, evt_ sign-in events, aud_ audit events, pkg_ access packages, req_ access requests, rev_ access reviews, lcr_ lifecycle rules, pol_ policies, nz_ network zones, dev_ devices, rsk_ risk events, key_ API keys, idp_ identity providers, whk_ webhooks, api_ API resources, spm_ SSH principal mappings and dom_ domains.
• Actions that return nothing answer 204 No Content.
• Every JSON response carries Cache-Control: no-store.

Errors

Every error has the same shape:

{"error": {"code": "ERR_NOT_FOUND", "message": "This user was not found. It may have been deleted."}}

Match on code, which is stable. Show message to people: it says what happened and what to do next.

The sign-in routes add their own codes:

Federated sign-in redirects to the sign-in page with its codes instead of answering JSON; Federation lists them.

Other areas return:

Route groups

Protocol endpoints

These endpoints follow their specifications rather than the conventions above.

Generic OpenID Connect, SAML 2.0 and Provisioning explain how to use them.

Examples

Invite a person

curl -X POST https://auth.example.com/api/v1/users \
  -H "Authorization: Bearer $HALO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "sam@example.com", "name": "Sam Lee", "department": "Engineering"}'

The response contains the new user and the enrollUrl to send to Sam, and emailed tells you whether Halo emailed it already. The link works once and expires at expiresAt, 7 days later by default. The key's service account needs the user administrator role.

Assign roles

Only a global administrator can assign roles, in the console under Roles or with the API. Send the complete list of roles; an empty list removes every role.

curl -X PUT https://auth.example.com/api/v1/users/usr_01J9Z…/roles \
  -H "Cookie: halo_session=$HALO_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"roles": ["user_admin", "auditor"]}'

The role keys are global_admin, security_admin, user_admin, helpdesk_admin, app_admin and auditor. GET /api/v1/users/{id} returns the role names, such as User administrator, in roles.

Register an application with two redirect URIs

curl -X POST https://auth.example.com/api/v1/applications \
  -H "Authorization: Bearer $HALO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Wiki", "protocol": "oidc", "type": "web",
       "redirectUris": ["https://wiki.example.com/auth/oidc.callback", "https://wiki.internal.example.com/auth/oidc.callback"],
       "groupIds": ["grp_01J9Z…"]}'

Store the clientSecret from the response: Halo does not show it again. Change the redirect URIs later with PATCH /api/v1/applications/{id}.

Approve every pending request you can decide

curl -s https://auth.example.com/api/v1/me/approvals -H "Cookie: halo_session=$HALO_SESSION" |
  jq -r '.[].id' |
  while read -r id; do
    curl -s -X POST "https://auth.example.com/api/v1/access-requests/$id/approve" -H "Cookie: halo_session=$HALO_SESSION"
  done