Docs/API Reference/Authentication
API Reference

Authentication

Secure your API requests using JWT tokens or API keys. Learn about authentication methods, token management, and best practices.

Authentication Methods

Decisio supports two authentication methods:

API Keys

Long-lived keys for server-to-server communication. Best for backend integrations and automation.

Recommended for backends

JWT Tokens

Short-lived tokens obtained via login. Best for user-facing applications and mobile apps.

Recommended for frontends

API Key Authentication

Creating an API Key

  1. Go to Settings → API Keys in your dashboard
  2. Click Create API Key
  3. Enter a description (e.g., "Production Backend")
  4. Select permissions (read-only or read-write)
  5. Copy the key immediately (it won't be shown again)

Using API Keys

Include the API key in the X-API-Key header:

curl -X GET "https://api.decisio.ai/v1/products" \
  -H "X-API-Key: dcs_live_xxxxxxxxxxxxxxxxxxxxxxxx"

API Key Prefixes

PrefixEnvironmentDescription
dcs_live_ProductionFull access to production data
dcs_test_SandboxTest environment, no real data

JWT Token Authentication

Obtaining Tokens

Exchange credentials for access and refresh tokens:

POST /auth/login
Content-Type: application/json

{
  "email": "user@company.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using Access Tokens

Include the access token in the Authorization header:

curl -X GET "https://api.decisio.ai/v1/decisions" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new one:

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Token Lifetimes

Token TypeLifetimeRenewable
Access Token1 hourYes, via refresh token
Refresh Token7 daysYes, returns new pair
API KeyUntil revokedN/A

Scopes & Permissions

API keys and tokens can be scoped to specific permissions:

ScopeAccess Level
read:productsView products and inventory
write:productsCreate/update products
read:decisionsView AI decisions
write:decisionsApprove/reject decisions
read:analyticsAccess reports and metrics
adminFull administrative access

Error Responses

401
Unauthorized— Missing or invalid authentication
403
Forbidden— Valid auth but insufficient permissions
429
Too Many Requests— Rate limit exceeded

Security Best Practices

  • Never expose API keys in client-side code
  • Store keys in environment variables, not source code
  • Use test keys for development, live keys only in production
  • Rotate keys periodically (quarterly recommended)
  • Set minimum necessary permissions for each key
  • Monitor API key usage in the dashboard
  • Revoke compromised keys immediately

Key Compromise

If you suspect an API key has been compromised, revoke it immediately from Settings → API Keys. Create a new key and update your integrations.

API OverviewWebhooks