Authentication

Account API keys

Create and manage account API keys in Dashboard → API Keys. Send your key in the Authorization header on every request:

Authorization: Bearer $DEVUP_API_KEY

On GET /v1/models, GET /v1/models/{model}, GET /v1/me, GET /v1/me/avatar, and POST /anthropic/v1/messages, the x-api-key header is also accepted. When both Authorization and x-api-key are sent, Authorization takes precedence on /v1/* endpoints.

Scoped JWT overview

A Scoped JWT is a server-signed JSON Web Token (eyJ...) that grants bounded inference access without exposing your primary sk-devup-... API key. Each Scoped JWT binds three independent controls directly to the credential:

• Permitted models — restrict calls to an explicit allowlist of 1–50 catalog models, or allow all models (*).
• Fixed expiration — automatically expires after a chosen duration between 1 hour and 90 days (2,160 hours), and can be revoked immediately at any time.
• Per-token DZD spending limit — tracks cumulative DZD usage attributed to the token between 1 DZD and 100,000 DZD against your account balance.

Scoped JWTs authenticate inference requests across POST /v1/chat/completions, POST /v1/responses, POST /anthropic/v1/messages, POST /v1/embeddings, POST /v1/rerank, POST /v1/images/generations, POST /v1/audio/speech, POST /v1/audio/transcriptions, POST /v1/video/generations, POST /v1/inference/{model}, and catalog discovery on GET /v1/models and GET /v1/models/{model}. See budget semantics and remaining allowance for how DZD spend is tracked against budget.

Creating and using Scoped JWTs

Scoped JWTs are signed by DEVUP AI and can only be minted from your authenticated dashboard:

1. Open Dashboard → API Keys, select the Scoped Tokens tab, and click Generate Scoped Token.
2. Set an optional display name (up to 50 characters, not starting with __), choose 1–50 allowed models (or enable Allow all models (*)), pick an expiration window (1 hour, 12 hours, 24 hours, 7 days, 30 days, or 90 days), and enter a spending limit between 1 and 100,000 DZD.
3. Copy the full eyJ... token immediately. For security, the full token string is shown only once at creation; the dashboard stores only a masked preview, cumulative spend, allowed models, and expiration metadata.

Token claims and permitted models

Every Scoped JWT is an HS256-signed compact JWS whose signature is verified on every request. Modifying any character of the header or payload invalidates the signature and returns HTTP 401 invalid_api_key. You can inspect a token's base64url-decoded claims client-side to check its model scope or expiration before sending a request:

{
  "alg": "HS256"
}

{
  "sub": "usr_01j8z9example",
  "models": [
    "deepseek-ai/DeepSeek-V4-Pro",
    "openai/gpt-5.3-codex"
  ],
  "budget": 250,
  "cache_key": "8f14e45f-ceea-467a-9a38-7b1f09example",
  "iat": 1761552000,
  "exp": 1761638400
}

Permitted model matching: Unless models contains "*", the model field in your request (or its resolved catalog ID from GET /v1/models) must appear in models. Requesting any other model returns HTTP 403 model_not_allowed before execution and is not billed. Each permitted model still enforces its own endpoint and capability rules published in GET /v1/models.

Token expiration and revocation

Every Scoped JWT has a mandatory expiration time (exp) between 1 hour and 90 days from creation. Once the expiration timestamp passes, all new requests with that token return HTTP 401 token_expired (for example, This scoped token expired at 2026-10-28T10:00:00.000Z.).

To cut off access before exp, click Revoke next to the token in Dashboard → API Keys → Scoped Tokens. Revocation takes effect immediately on subsequent requests, returning HTTP 401 token_revoked (This scoped token has been revoked.). Because claims are cryptographically signed at creation, neither exp, models, nor budget can be edited in place; issue a new Scoped JWT when rotating credentials or changing limits.

Budget semantics and remaining allowance

Each Scoped JWT tracks cumulative DZD spend attributed to that token alongside your account's DZD balance:

• Pre-request cumulative check: On every request, DEVUP AI checks the token's recorded DZD spend against its signed budget. Once recorded spend reaches or exceeds budget, new requests with that token return HTTP 402 budget_exhausted before execution.
• Post-execution usage attribution: When a billed request completes, its verified DZD cost is deducted from your account balance and added to the token's cumulative spend counter shown in Dashboard → API Keys → Scoped Tokens.
• Concurrent requests and explicit output bounds: Because token spend is recorded upon request completion, multiple requests started in parallel before recorded spend reaches budget are each checked against the spend already recorded at admission. Pass conservative max_completion_tokens or max_output_tokens values when callers run concurrent requests on a shared token.

Relationship between token limits and account balance

A Scoped JWT does not create a separate prefunded sub-wallet. All billed usage is deducted in Algerian dinars (DZD) from the issuing account's balance while also counting against the token's signed budget. Every request must pass both checks:

• Effective ceiling: Available spend for a request is bounded by whichever limit is lower—your available account DZD balance or the token's remaining DZD allowance. A token with a 1,000 DZD limit on an account holding 50 DZD stops with insufficient_balance once the 50 DZD balance is used.
• Top-ups do not reset token spend: Adding DZD to your account restores insufficient_balance capacity, whereas an exhausted Scoped JWT remains at budget_exhausted once its settled spend reaches budget.
• Partial-balance fitting on text endpoints: On POST /v1/chat/completions and POST /anthropic/v1/messages, a request without tools is answered with a reduced max_tokens when your account balance covers part of the reply (notice max_tokens_capped_by_balance).
• Separate from rate limits: Waiting for a per-minute rate limit window never replenishes a token's DZD spending limit.

Common Scoped JWT errors

Scoped JWT errors use the standard OpenAI-compatible JSON envelope (error.type = "devup_error", error.code, error.message) and include x-request-id. Match on error.code in client code:

• Prefer explicit model allowlists over *: Grant only the exact models a workflow needs so a leaked token cannot invoke higher-cost text, image, audio, or video models.
• Issue short lifetimes for untrusted environments: Choose 1-hour or 24-hour expirations when handing tokens to browser sessions, CI jobs, or third-party previews, and rotate tokens before exp.
• Bound per-request output tokens: Always pass max_completion_tokens or max_output_tokens alongside conservative DZD budget values, especially when callers can submit concurrent requests.
• Never commit credentials to source control: Store tokens in environment variables or a secret manager, and revoke any exposed token immediately in Dashboard → API Keys → Scoped Tokens.
• Correlate requests with x-client-request-id: Send a per-operation x-client-request-id (1–64 characters of A-Za-z0-9._:-) and log the returned x-request-id so usage and errors can be traced cleanly.

Compatibility and migration notes

• No credential rotation required: Existing sk-devup-... API keys and existing eyJ... Scoped JWTs remain valid byte-for-byte with their current signatures, cache_key identifiers, model allowlists, expiration timestamps, and prior recorded spend.
• Drop-in SDK compatibility: Pass a Scoped JWT wherever the OpenAI SDK expects apiKey / api_key (with baseURL: "https://api.devupai.com/v1") or wherever the Anthropic SDK expects apiKey / authToken on https://api.devupai.com/anthropic. No request parameter changes are required.
• Forward-compatible error handling: Match programmatically on error.code, honor Retry-After on HTTP 429 and HTTP 503 responses, do not retry HTTP 400 scoped_budget_unbounded_request or HTTP 401/403 credential rejections with the same request, and do not blindly replay HTTP 409 request_outcome_pendingwithout checking the prior request's outcome.