Skip to content

API Tokens

API tokens provide programmatic access to Devici using OAuth2 client credentials.

This feature supports fine-grained scope-based permissions, optional IP allowlisting, usage tracking, audit logging, and automated cleanup of inactive tokens.

Availability and Access Control

API tokens are available only for:

  • Enterprise tier organizations
  • Owner or Superadmin users (create and manage tokens)
  • Tokens assigned to users with Owner, Superadmin, or Admin roles with scopes applied

How API Tokens Work

Each API token includes:

  • client_id (public identifier)
  • client_secret (secret)

The client_secret is shown only once during creation or regeneration and must be stored securely.

API tokens authenticate using OAuth2 client credentials, resulting in a JWT used for API requests.

Scopes and Permissions

API tokens use scope-based permissions in the format:

  • {resource}:{permission} (example: threat-models:read)

Permissions:

  • READ
  • WRITE

At least one scope is required per token.

Scope Presets

Devici provides preset scope bundles for common use cases (for example: read-only, full access, threat-models read/full, analytics, security, codex, CLI).

Use presets whenever possible to reduce misconfiguration.

IP Allowlisting

You can optionally restrict a token to specific IP addresses:

  • Individual IPs (example: 192.168.1.1)
  • CIDR ranges (example: 192.168.1.0/24)

If no IP allowlist is configured, the token can be used from any IP.

Requests from non-allowlisted IPs are rejected with 403 Forbidden.

Token Lifecycle Management

Super-admins can:

  • Create tokens
  • Update title and description
  • Update scopes
  • Update IP allowlist
  • Regenerate credentials (invalidates old credentials)
  • Enable or disable tokens
  • Transfer tokens to another eligible user
  • Delete tokens

Limits:

  • Maximum 50 API tokens per organization
  • Title required (max 100 characters)
  • Description optional (max 500 characters)

Usage Tracking and Audit Logging

Devici tracks token usage:

  • Last used timestamp is recorded for each token

All token operations are audit logged, including:

  • Creation
  • Updates (metadata, scopes, IP allowlist)
  • Transfer
  • Credential regeneration
  • Enable/disable
  • Deletion

Automatic Cleanup of Inactive Tokens

Devici automatically manages unused tokens to reduce risk and clutter.

  • After 1 month of inactivity: token is automatically disabled
  • After 2 months: warning notification is sent
  • 1 week before removal: final warning notification is sent
  • After 3 months: token is automatically removed

Using the token for any API request resets its inactivity timer.

Common Errors

Authentication failures (401 Unauthorized) can occur when:

  • Authorization header is missing or invalid
  • Token is disabled
  • Token has no assigned user
  • Token has no scopes configured

Authorization failures (403 Forbidden) can occur when:

  • Token lacks required scope
  • IP is not allowlisted
  • Client IP cannot be determined

Next Steps

To learn how to use the API once you have a token, see: