Skip to main content

API Tokens

O.D.I.N. provides three authentication mechanisms for API access. Scoped API tokens are the recommended option for automation, integrations, and CI/CD pipelines.

Authentication Methods Comparison​

MethodFormatExpiryScopeUse Case
System API KeyStatic key set on installNeverFull API accessInternal services, monitors
Session JWTAuthorization: Bearer <jwt>24 hoursFull user role accessInteractive API clients
Scoped Tokenodin_... prefixConfigurablePer-route granular scopesAutomation, third-party tools

Creating a Scoped Token​

  1. Go to Settings → Account → API Tokens
  2. Click New Token
  3. Enter:
    • Name — a descriptive label (e.g., "Grafana read-only", "CI/CD deploy")
    • Scopes — select one or more from the available scopes table
    • Expiry — leave blank for no expiry, or set a date
  4. Click Create
  5. Copy the token immediately — it will not be shown again
Token Displayed Only Once

The full token value is displayed only at creation time. O.D.I.N. stores only a bcrypt hash of the token. If you lose it, delete the token and create a new one.

Available Scopes​

Operator scopes (per-resource)​

ScopeAccess
read:printersRead printer status, telemetry, filament slots
write:printersCreate, update, delete printers
read:jobsRead job queue and job details
write:jobsCreate, update, cancel jobs
read:spoolsRead spool inventory
write:spoolsCreate, update, delete spools
read:modelsRead model library
write:modelsUpload and manage models
read:analyticsRead analytics and reports
read:ordersRead orders and invoices
write:ordersCreate and update orders
read:usersRead user list (admin-level scope)

Agent scopes (v1.8.9+)​

For AI-agent-driven operation via the MCP server or equivalent. These scopes grant a curated slice of the operator surface designed to be safe for autonomous use.

ScopeAccess
agent:readDashboard visibility — printers, jobs, queue, alerts, spools, filaments, maintenance tasks, orders. No state changes.
agent:writeagent:read + queue/cancel/approve/reject jobs, pause/resume printers, manage spools & alerts, log maintenance.

Agent scopes do not grant access to auth / license / backup / user-CRUD / SMTP config / RBAC management. Those stay humans-only regardless of token scope.

Grant the narrowest scope that works for the agent's job. agent:read is the recommended starting scope while evaluating an agent; upgrade to agent:write after verification.

Using a Token​

Include the token in the Authorization header using the Bearer scheme.

Read-Only Example (Fetching Printer Status)​

curl -H "Authorization: Bearer odin_abc123def456..." \
  https://your-odin-host/api/printers

Write Example (Creating a Job)​

curl -X POST \
  -H "Authorization: Bearer odin_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{"model_id": 42, "printer_id": 1, "priority": "normal"}' \
  https://your-odin-host/api/jobs

Tokens with insufficient scope for an endpoint receive a 403 Forbidden response.

Revoking Tokens​

  1. Go to Settings → Account → API Tokens
  2. Click Revoke next to the token you want to delete
  3. The token is immediately invalidated

Tokens are stored by hash — revoking deletes the hash record, blocking all future requests with that token.

Token Prefix and Identification​

All scoped tokens are prefixed with odin_. The first 8 characters after the prefix form the token prefix (token_prefix column), which is displayed in the token list so you can identify which token corresponds to which integration without exposing the full secret.

See Also​