Skip to main content

API tokens

API tokens are long-lived credentials for programmatic access to Praxis and related HTTP APIs, scoped to an organization and a tenant. In the product they are created only from tenant context: Tenant settings → API Tokens (see Tenants). You need a visible tenant in the org/tenant switcher, and a role that is allowed to create tokens.

Programmatic callers must send both x-ne-org-id and x-ne-tenant-id on every request — the token is bound to a single org/tenant and identity-service rejects calls whose headers do not match that binding. See Using API tokens for the full request shape.

Typical path pattern: …/identity/settings/tenant?tenant=<id>&tenantName=<name>&orgId=<orgId>&tab=api-tokens

Creating a token​

Create or new token opens a modal where you:

  • Give the token a name (for example ci-deploy-east).
  • Choose permissions in one of two ways (as implemented in the UI):
    1. Permission sets — Quick bundles such as Read only (pipelines, collectors, metrics – read), Data access (adds read/write for those data paths), and Full access (all scopes your deployment exposes for the token system).
    2. Custom — Pick individual scopes from the list returned by list permissions for your org, grouped by resource (for example pipeline, collector, metrics, organization, tenant).

The secret is shown once in a drawer or confirmation panel. Store it in a secret manager; you cannot retrieve the same secret again from the server.

Listing and revoking​

The API Tokens tab shows existing tokens in a table with pagination and sorting where the design system provides them. Each row can offer revoke (or delete), which invalidates the token after confirmation. After revocation, API calls using that value fail with your gateway’s 401/403 behavior.

Scopes and security​

  • Scopes are string values such as pipeline:read, pipeline:write, collector:read, metrics:read, and related organization / tenant / user / alerts / knowledge names as your deployment registers them.
  • Use the smallest set needed. Prefer a read-only or data-access bundle over full unless automation must manage users or org settings.
  • Tokens are tenant–scoped: they can only act within the tenant (and org) for which they were created.
  • If creation fails, the UI shows an error; common causes are missing org/tenant context, insufficient rights, or server validation errors.

Automation vs user sessions​

API tokens are not a replacement for end-user login or SSO. Use them for CI/CD, runbooks, and daemons; use interactive login (password or SSO) for human administrators.