SDK overview
Compare Apikee SDKs for Python, Node.js, Java, and .NET. Learn their shared key format, claims, configuration, and local and server modes.
Four SDKs, one design. They verify the same key format with the same algorithm, so a key issued by your Python service verifies in your .NET service as long as they share a signing secret.
Two modes
Local mode — a signing secret and nothing else. Keys are self-contained, so verification is pure CPU with no I/O. Zero dependencies.
Server mode — add three variables pointing at your instance. You keep the local fast path and additionally get revocation, usage logs, IP allow-lists, rate limits and auto-registered endpoints.
| Local | Server | |
|---|---|---|
| Signature, scopes, expiry | ✓ | ✓ |
| Latency on the hot path | ~0.1ms | ~0.1ms |
| Revoke a key | ✓ | |
| Per-key usage and logs | ✓ | |
| IP allow-lists, rate limits | ✓ | |
| Endpoint registry and docs | ✓ |
Moving between them changes configuration, not route code.
Configuration
Every SDK reads the same four environment variables.
export APIKEE_SECRET=$(openssl rand -hex 32) # required, both modes
# Server mode only
export APIKEE_BASE_URL=https://apikee.example.com/api/v1
export APIKEE_SERVER_KEY=sk_...
export APIKEE_PROJECT_ENV=payments-api-production.NET reads its secret as Apikee__Secret via standard configuration binding; the
other three are shared.
Common options
| Option | Default | Meaning |
|---|---|---|
secrets | from env | Array. First is used to sign; all are tried when verifying, which is how you rotate. |
headerName | x-api-key | Header the key is read from. |
failOpen | true | If the platform is unreachable, serve on the strength of the local check. |
autoRegisterEndpoints | true | Register routes as traffic arrives. |
autoCreateClients | true | Create a client record on first sight. |
timeout | 3000ms | Platform request timeout. |
privateKey | — | PEM key for request signing. |
serverPublicKey | — | Enables payload encryption to the platform. |
failOpen: true means an unreachable platform degrades you to local-mode
guarantees — valid signatures still pass, but revocation and rate limits are not
checked. Set it to false if you would rather reject than under-enforce.
The claims object
Verification returns the same shape everywhere, named idiomatically per language.
| Field | Type | |
|---|---|---|
id | string | Key identifier |
tenant | string | Who the key belongs to |
scopes | string[] | Granted capabilities |
environment | string | Issuing environment |
expiresAt | date | null | |
notBefore | date | null | |
meta | object | Arbitrary JSON attached at issuance |
Where to find it:
| Python | ApikeeDepends(), or get_claims() in Flask |
| Node.js | req.apikee · c.get('apikee') in Hono |
| Java | request.getAttribute("apikee.claims") |
| .NET | HttpContext.Items["apikee.claims"] |
Errors
A failed verification raises a typed error carrying a stable code, so you can map
outcomes to responses without string-matching:
| Code | Meaning | Suggested status |
|---|---|---|
MISSING_KEY | No header present | 401 |
INVALID_KEY | Malformed, or signature does not verify | 401 |
EXPIRED_KEY | Past expiresAt | 401 |
NOT_YET_VALID | Before notBefore | 401 |
MISSING_SCOPE | Authenticated but not permitted | 403 |
The bundled middleware already maps these. You only handle them yourself when using the inline guard in a framework with no adapter.
No adapter for your framework?
Every SDK exposes an inline guard that takes a header value and returns claims, so
it works anywhere you can reach the request — Koa, Next.js route handlers, raw
http, a message consumer.
const claims = apikee.protect(req.headers['x-api-key'])AI and the SDKs
The SDKs contain no AI code and take on no AI dependency. What they do is describe your endpoints to your own instance, which is what lets the platform's assistant and generated docs talk about your API accurately.