Skip to content

Last update: October 15, 2026

Authentication

All requests to the Djinn API must be authenticated with an API key.

Mechanism — X-API-Key

Include your API key in the X-API-Key header of every request:

curl -H "X-API-Key: your_api_key" \
     https://api.dev.djinn.solyntek.io/v1/extract

API keys are issued by the Solyntek team during onboarding. They cannot be self-provisioned via the API.

Tenant Isolation

Each API key is associated with a single tenant. All your data, knowledge bases and audit logs are strictly isolated from other tenants. It is not possible to access another tenant's data, even with a valid key.

Rate Limiting

Requests are limited per API key by the gateway: 60 requests per minute and 1,000 per hour on all routes. POST /v1/hr/subjects/ref (candidate-analyzer) is limited more strictly, to 10 per minute and 100 per hour. The counters are kept by each gateway instance, so the effective quota can be slightly higher than these values; do not rely on that margin. If the limit is exceeded, the API returns 429.

Every response carries the counters: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Hour and X-RateLimit-Remaining-Hour. A 429 also carries a Retry-After header (seconds).

Error Codes

HTTP Code Meaning
401 Unauthorized Missing, invalid or revoked API key
403 Forbidden Valid API key but access denied: for example a tenant_id that is not the one of your key (audit-trail)
429 Too Many Requests Rate limit reached — wait before retrying

Two formats exist, depending on who answers:

  • The gateway (Kong) answers 401 and 429 with {"message": "..."}.
  • The services answer with FastAPI's format, {"detail": ...}: detail is a string ({"detail": "Invalid API key"}) or, for some business errors (candidate-analyzer, doc-trust), an object {"code": "...", "message": "..."}. A request that fails validation answers 422 with detail as a list of problems.

Example 401 Response

{
  "message": "No API key found in request"
}

An unknown key gets {"message": "Invalid authentication credentials"}; a key refused by the service itself (revoked) gets {"detail": "Invalid API key"}.

Example 429 Response

{
  "message": "API rate limit exceeded"
}

Best Practices

  • Never expose your API key in versioned source code — use environment variables
  • Rotate your staging and production keys separately
  • Contact Solyntek immediately if you suspect a key has been compromised