API Keys
The credential the Praxis CLI, pipelines, and scripts use to authenticate to Praxis for unattended, non-interactive work.
A Praxis API key is a long-lived credential that authenticates you to Praxis without an interactive sign-in. You send it as a bearer token, and each request runs through the same gateway, under the same permissions, as a chat session. For working from your own machine, the browser-based praxis login is the better choice, and keys are for the unattended case. See Praxis CLI.
A key is not the same thing as a Facets personal access token. That distinction is at the end of this page.
Create an API key
You create and manage keys under Settings > API Keys. Creating one needs an interactive sign-in, and a key cannot create another key.
- Choose Create API Key.
- Give the key a name and an optional description of what it is for. The name is lowercase letters, numbers, hyphens, and underscores, and has to be unique in your organization, so name it for the pipeline or integration that will use it.
- Copy the key the moment Praxis shows it, and store it in your secrets manager or CI secret store. The full value appears only once, at creation.
Praxis keeps only a hash of the key, never the value, so a key you lose cannot be shown to you again. Create a new one instead.
Use a key
Send the key as a bearer token on every request:
Authorization: Bearer <your-key>Keep the value out of source control and out of your shell history. Store it in a secrets manager and read it from an environment variable at run time. To run the Praxis CLI from CI or cron, see Praxis CLI. To call Praxis directly, the gateway resolves your organization and user from the key and runs the requested tool server-side. For that path and how it stays audited, see How Praxis works.
What a key can and cannot do
A key acts as the person who created it. It carries exactly that person's permissions, scoped to your organization, and there are no separate per-key scopes. Removing that person's access, or their membership in the organization, stops the key working. For how the gateway enforces this on every call, see How Praxis works.
A key is deliberately limited to doing work, not to administering the account. It cannot:
- create or manage API keys, including its own,
- change account or profile settings.
Those actions require an interactive sign-in. Every call a key makes is attributable to that key and written to the audit trail.
Replace or delete a key
Praxis has no separate revoke or rotate step. To rotate a key, create a new one, move your systems over to it, and delete the old one. To retire a key for good, delete it. You confirm a delete by typing the key's name, and it takes effect immediately.
Deleting a key is permanent and cannot be undone. Every system still using that key fails authentication the moment it is deleted, so move your automation to a new key first.
Praxis API keys vs Facets tokens
A Praxis API key authorizes the Praxis agent. It is not your Facets personal access token (PAT), which authenticates to the Facets Control Plane API and the raptor CLI over HTTP Basic auth. They are separate credentials for separate systems. To create a PAT, see Generate a personal access token. For the control plane's REST API, see the API Reference.
Related
- Praxis CLI - Run Praxis from your terminal and CI, and log in from a browser
- How Praxis works - The gateway, permissions, and audit model behind every key
- Connect a Tool - Reference stored credentials your agents use
- API Reference - The Facets Control Plane REST API and its personal access token
Web Component Builder
Build custom Facets dashboard components by describing them to Praxis, which scaffolds the code, deploys it to GitHub Pages, and embeds the result in your dashboard.
Databases
Create SQLite databases that Praxis hosts, attach them to your agents, and give each agent tools to store, query, and update structured data as it works.