Auth - cliq

Credentials

Use the smallest credential that fits the job. Privilege lives on the token grant, not on an /admin URL.

Cheat sheet

I am…	Use	How you get it
A person in the terminal or browser	Session JWT	`cliq login` (or Hub `POST /v1/auth/login`)
CI / a script talking to Hub	User token `cliq_tok_…`	`cliq auth token <name>` (type `user`)
A daemon joining a realm	Realm token `cliq_dt_…`	Realm page in Hub console, or `cliq realm token <realm_id> <name>`
CLI talking to a non-local daemon	Dispatch JWT	`cliq auth daemon-key` + mint via Hub API → Dispatch
CliqHub BFF provisioning users/orgs	Service grant (internal)	Never public — not documented on this site

All of these go in the header as:

Authorization: Bearer <token>

Token types on Hub are only user | realm. Legacy personal / daemon types are rejected.

API planes

Plane	Where	Who calls it
Hub API (`/v1`)	Public product API	People, CI, daemons (with the right credential)
Internal API (`/internal`)	Not on public ingress	CliqHub BFF only — signup, delete user/org, other tenancy admin. Spec is private (not published here).
Daemon API	Your machine (`localhost`)	CLI and local tools

There is no /admin route tree. The same resource paths serve everyone; the grant decides if the call is allowed. Interactive specs on this site: Hub API and Daemon API only.

Grants (domains + access)

Every user and realm token carries a grant:

{
  "domains": {
    "orgs": [42],
    "scopes": ["acme"],
    "realms": ["…"]
  },
  "access": {
    "teams": ["read", "write"],
    "runs": ["read", "write"],
    "dispatch": ["write"],
    "users": ["read"]
  }
}

Domains — where the credential may act (orgs / scopes / realms).
Access — per entity, one or more of read | write | admin.
- read — get / list (including run details and logs)
- write — create / update / publish / dispatch / cancel / heartbeat
- admin — irreversible tenancy ops (delete user/org, rotate org keys, …)

Dispatch is a write (usually runs:write or dispatch:write). Run events, logs, phases, and artifacts share the runs entity — they are not separate domains.

Mint templates

CI publisher

{
  "domains": { "orgs": [42], "scopes": ["acme"] },
  "access": {
    "teams": ["read", "write"],
    "runs": ["read", "write"],
    "dispatch": ["write"]
  }
}

Realm enroll token

{
  "domains": { "realms": ["<realm_id>"] },
  "access": {
    "daemons": ["write"],
    "dispatch": ["write"],
    "runs": ["read", "write"]
  }
}

Platform / BFF (internal callers)

{
  "domains": { "orgs": "*", "scopes": "*", "realms": "*" },
  "access": {
    "users": ["admin"],
    "orgs": ["admin"],
    "scopes": ["admin"]
  }
}

Session (people)

cliq login
cliq whoami

Headless:

cliq login --headless username:alice password:secret

Accounts are not created via a public signup API. Provisioning goes through CliqHub BFF → private Hub /internal routes. Day-to-day login stays on Hub API.

User token (automation)

cliq auth token ci-pipeline
# → cliq_tok_… shown once — store the grant with the token

Use that Bearer value on Hub API the same way you’d use a session JWT, limited by the grant. Rotate or revoke from the console (Account → Tokens) or Hub API → Tokens with type: "user".

Realm token (machines)

Mint on the realm page in Hub, or:

cliq realm token <realm_id> laptop-enroll
# → cliq_dt_… shown once

export CLIQ_DAEMON_ID=edge-1
export CLIQ_DAEMON_TOKEN=cliq_dt_…
cliq daemon restart

Daemons reject user JWTs and user tokens for enroll / heartbeat / job pickup. If register fails with 401, you’re almost certainly using the wrong token type — use a realm token (cliq_dt_…).

What each surface expects

Surface / area	Credential	Grant
Hub Auth login, me, tokens	Session or user token	— / `tokens:*`
Orgs, scopes, teams (product)	Session or user token	`orgs` / `scopes` / `teams` read·write·admin
Realms, mint realm tokens	Session or user token	`realms` write
Daemons list	Session or user token	`daemons` read
Daemons register / heartbeat	Realm token	`daemons` write
Dispatch install / run / cancel	Session or user token	`dispatch` / `runs` write
Dispatch poll	Realm token	`dispatch` write
Signup, delete user/org, set role	BFF → internal Hub routes (not public)	`users` / `orgs` / `scopes` admin

Mental model → Concepts
CLI login / tokens → CLI
Path checklist for implementers → design/api-route-permissions.md in the repo

​Cheat sheet

​API planes

​Grants (domains + access)

​Mint templates

​Session (people)

​User token (automation)

​Realm token (machines)

​What each surface expects

​Related

Cheat sheet

API planes

Grants (domains + access)

Mint templates

Session (people)

User token (automation)

Realm token (machines)

What each surface expects

Related