Using API tokens

After you create a token in API tokens, use this page to actually call the Praxis API with it. Tokens are tenant-scoped and meant for CI/CD, runbooks, and daemons — not for human sign-in.

Authenticate

Pass the token in the standard Authorization header on every request:

Authorization: Bearer <YOUR_TOKEN>

Example with curl:

export PRAXIS_TOKEN='paste-the-token-shown-once-on-creation'

curl -sS https://praxis.example.com/v1/pipelines \
  -H "Authorization: Bearer ${PRAXIS_TOKEN}" \
  -H "Accept: application/json"

The base URL depends on your deployment. The /identity/… and /v1/… examples below use the default Praxis path layout. Substitute your environment's host and any reverse-proxy prefix.

Set the org/tenant context

A token is bound to the organization and tenant it was created in, so you do not need to send those IDs again for most calls. Where an endpoint accepts an explicit context (or where your gateway requires it), pass:

x-ne-org-id: <organization uuid>
x-ne-tenant-id: <tenant uuid>

You can find both IDs in the deep-link URL of Tenants (?orgId=…&tenant=…), or via an authenticated session call to the org/tenant list endpoints documented in the API reference.

Pick the right scopes

The scopes you choose at creation time bound what the token can do — even if the issuing user has more privileges. Prefer the smallest set that gets the job done.

Use case	Suggested scopes
Read pipeline state from a dashboard	pipeline:read, optionally collector:read, metrics:read
Promote a pipeline change from CI	pipeline:read, pipeline:write
Sync collector inventory into your CMDB	collector:read
Pull alerts into an on-call tool	alerts:read
Fully manage a tenant from automation	the Full access preset, or an explicit *:write set

Scopes are strings of the form <resource>:<action>. The full list available to your org is what the Custom picker shows when you create a token.

Tokens cannot create or modify users, organizations, or SSO connections unless the scopes include the relevant organization:* / user:* capabilities and the issuing user holds those roles. Treat user/org administration as a session action, not a token action.

Common request patterns

List pipelines in the current tenant

curl -sS https://praxis.example.com/v1/pipelines \
  -H "Authorization: Bearer ${PRAXIS_TOKEN}"

Read a single resource

curl -sS https://praxis.example.com/v1/pipelines/<pipeline-id> \
  -H "Authorization: Bearer ${PRAXIS_TOKEN}"

Create or update (write scope required)

curl -sS -X POST https://praxis.example.com/v1/pipelines \
  -H "Authorization: Bearer ${PRAXIS_TOKEN}" \
  -H "Content-Type: application/json" \
  --data @pipeline.json

Pass explicit org/tenant context

curl -sS https://praxis.example.com/v1/pipelines \
  -H "Authorization: Bearer ${PRAXIS_TOKEN}" \
  -H "x-ne-org-id: 11111111-1111-1111-1111-111111111111" \
  -H "x-ne-tenant-id: 22222222-2222-2222-2222-222222222222"

Storing the secret

The token secret is shown once when you create it — there is no way to retrieve it again from the server. Store it in a real secret manager.

Environment	Recommended store
GitHub Actions	Repository or organization Actions secrets
GitLab CI	CI/CD variables (masked, protected)
Kubernetes	A Secret mounted as an env var or file
Local dev	.env (gitignored) — never commit

Bad places: source code, build logs, screenshots, or shared chat tools.

Rotate and revoke

Tokens do not auto-expire; you decide when to rotate them.

• Rotate — Create a new token with the same scopes, deploy it everywhere, then revoke the old one. There is intentionally no in-place "regenerate" so the new and old can overlap during a deploy.
• Revoke — In the API Tokens tab, choose Revoke (or Delete) on the row. After revocation, calls using that secret start failing immediately at the gateway with 401 or 403.
• Audit — Treat each token name as a purpose (for example ci-deploy-east, oncall-grafana). When you no longer recognize a token, revoke it.

A leaked or compromised secret should be revoked first, then replaced — not the other way around.

Error responses (quick reference)

Status	Likely cause	What to do
401 Unauthorized	Missing or malformed Authorization header; token revoked or never existed.	Check the header is Bearer <token> and the token is still listed in API Tokens.
403 Forbidden	Token does not carry the scope this endpoint requires; or org/tenant context mismatch.	Recreate with the right scopes, or set x-ne-org-id / x-ne-tenant-id to match.
404 Not Found	The resource does not exist in the current tenant.	Confirm you are calling against the right tenant — tokens are tenant-scoped.
429 Too Many Requests	Rate limited by the gateway.	Back off and retry; consider batching.

Tokens vs sessions vs SSO

Method	What it is	When to use
Session cookie	Created on interactive sign-in (password or SSO).	Humans using the Praxis UI.
API token (this page)	Long-lived bearer secret with explicit scopes, tied to a tenant.	Automation: CI, runbooks, scripts, daemons.
SSO	Identity-provider-driven sign-in for human users.	Humans whose identity is centrally managed by Okta, Entra ID, Google Workspace, Auth0, etc.

Do not use API tokens to act on behalf of a human — they have no concept of "who is using them right now." For human sign-in, use SSO or password.

See also

• API tokens — creating, listing, revoking tokens in the UI.
• Concepts and terminology — what scope, role, and tenant mean here.
• Troubleshooting — common 401/403 patterns.