Keys, Tags & Budgets.
Organisation and roles, API keys with permissions and euro budgets, request tags (/v1/tags), prepaid credit, and /v1/models and /v1/prices.
An organisation owns its API keys, own providers (BYOK), policies and credit balance; members access it in the portal per organisation either as an Admin (invite and remove members, change roles, create and revoke keys, connect BYOK providers, edit settings, top up credit) or as a Member (read-only access to keys, usage, settings and balance).
Organisation, roles and API keys.
Every API key starts with px-, belongs to the organisation and is displayed in full once upon creation under Models → API keys (New key); a revoked key fails immediately with 401 invalid_api_key and can be reactivated or permanently deleted:
| Scope | Setting | Effect & portal location |
|---|---|---|
| Organisation | Shield policy & filters | Default mode (default_off, default_on, enforced), five protection filters and custom_patterns under Models → Shield (see Noirdoc Shield). |
| Organisation | Advanced settings | allow_stored_responses (Responses API provider storage, new organisations: off) and allow_file_content (file/image/audio parts, default: on) under Models → Shield. |
| Organisation | Own providers (BYOK), § 203 & credit | Priority BYOK keys under Models → Providers, § 203 classification on Getting started (see Providers, Routing & § 203) and balance under Billing. |
| API key | Models, providers & shield_mode | Allowed models, data residency, CLOUD Act, § 203, provider allowlist and Shield (inherit, on, off) under Models → API keys. |
| API key | Budget (€) | Optional spending cap per key with configurable reset window (402 key_budget_exhausted). |
| API key | can_manage_shield | Manage Shield policy via API enables /v1/shield/policy; a key pinned to on cannot weaken the policy (403 insufficient_key_permissions). |
| API key | can_manage_tags | Allow tag management (/v1/tags) enables /v1/tags and /v1/tags/_default within the calling key’s own model, provider and Shield restrictions (403 insufficient_key_permissions). |
One key per application: Create a dedicated
px-key for each application and environment (for examplechatbot-prodandchatbot-staging) so budgets, model restrictions and revocations stay isolated.
Per-key budgets.
A euro budget caps spend on a single API key while all other keys in your organisation keep working. On HTTP 402, inspect error.code to distinguish credit exhaustion from key or tag budgets:
import openai
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
try:
client.chat.completions.create(
model="qwen3.8-27b",
max_tokens=500,
messages=[{"role": "user", "content": "Summarise."}],
)
except openai.APIStatusError as err:
if err.status_code == 402:
code = err.response.json()["error"]["code"]
# "insufficient_credit" | "key_budget_exhausted"
# | "tag_budget_exhausted"import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
try {
await client.chat.completions.create({
model: "qwen3.8-27b",
max_tokens: 500,
messages: [{ role: "user", content: "Summarise." }],
});
} catch (err) {
if (err instanceof OpenAI.APIError && err.status === 402) {
// err.code: "insufficient_credit" | "key_budget_exhausted"
// | "tag_budget_exhausted"
}
}curl -s https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"max_tokens": 500,
"messages": [{"role": "user", "content": "Summarise."}]
}' | jq '.error.code'{
"error": {
"type": "insufficient_quota",
"code": "key_budget_exhausted",
"message": "This request could cost up to 0.42 EUR, more …",
"param": null
}
}Before forwarding, the gateway checks organisation credit first (insufficient_credit), then the key budget (key_budget_exhausted), and finally attached tag budgets in header order (tag_budget_exhausted).
| Aspect | Rule |
|---|---|
| Reset windows | Daily (00:00 UTC), Weekly (Mondays at 00:00 UTC), Monthly (1st of the month at 00:00 UTC) or Never (lifetime of the key; empty = no cap). |
| Counted spend | Priced managed models (status < 400) plus the Noirdoc Shield inspection fee (+€0.40 per 1M inspected input tokens, including on BYOK routes with active Shield, 403 shield_violation blocks and POST /v1/shield/inspect; BYOK without active Shield and legacy masking until 30.11.2026 count as €0.00). |
| Pre-flight estimate | Chat/embeddings: JSON input character length divided by 4 (+ €0.40 / 1M tokens when Shield is active) plus max_tokens / max_completion_tokens / max_output_tokens (defaults to 4,096 chat output tokens when omitted – set a realistic max_tokens near the cap). Images: count × price per image/megapixel. Audio: checks only whether budget remains. |
Request tags (Preview).
Preview: Request tags are available in Preview for selected organisations. Email hello@noirdoc.de to enable them. Without activation, the gateway rejects the
X-Noirdoc-Tagsheader and calls to/v1/tagswith403 request_tags_disabled.
Pass 1 to 5 comma-separated tag names in X-Noirdoc-Tags (deduplicated and stripped before forwarding; also evaluated by GET /v1/models and POST /v1/shield/inspect) to attach per-matter, cost-centre or team budgets, model/provider rules and shield_mode without issuing separate API keys. Tag names match ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$ (_default is reserved for /v1/tags/_default; capped at 1,000 tags per organisation before 403 tag_limit_exceeded). Under Models → Tags, unknown tags auto-create on the first forwarded request from the _default template by default (tag_auto_create_enabled: true; when turned off, unknown tags fail with 403 tag_not_found):
import os
import httpx
from openai import OpenAI
key = os.environ["NOIRDOC_API_KEY"]
httpx.put(
"https://api.noirdoc.de/v1/tags/mandat-2026-042",
headers={"Authorization": f"Bearer {key}"},
json={
"description": "Matter 2026/042 – Employment law",
"budget_limit_eur": 25.0,
"budget_reset": "monthly",
"shield_mode": "on",
"allowed_residencies": ["DE", "EU"],
"require_no_cloud_act": True,
"require_section203": True,
},
).raise_for_status()
client = OpenAI(base_url="https://api.noirdoc.de/v1", api_key=key)
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Check deadlines."}],
extra_headers={
"X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht"
},
)import OpenAI from "openai";
const key = process.env.NOIRDOC_API_KEY!;
await fetch("https://api.noirdoc.de/v1/tags/mandat-2026-042", {
method: "PUT",
headers: {
Authorization: `Bearer ${key}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
description: "Matter 2026/042 – Employment law",
budget_limit_eur: 25.0,
budget_reset: "monthly",
shield_mode: "on",
allowed_residencies: ["DE", "EU"],
require_no_cloud_act: true,
require_section203: true,
}),
});
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: key,
});
await client.chat.completions.create(
{
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Check deadlines." }],
},
{ headers: { "X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht" } },
);curl -X PUT https://api.noirdoc.de/v1/tags/mandat-2026-042 \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "Matter 2026/042 – Employment law",
"budget_limit_eur": 25.0,
"budget_reset": "monthly",
"shield_mode": "on",
"allowed_residencies": ["DE", "EU"],
"require_no_cloud_act": true,
"require_section203": true
}'
curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "X-Noirdoc-Tags: mandat-2026-042,team-arbeitsrecht" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "Check deadlines."}]
}'{
"name": "mandat-2026-042",
"description": "Matter 2026/042 – Employment law",
"is_active": true,
"budget_limit_eur": 25.0,
"budget_reset": "monthly",
"budget_spent_eur": 0.0,
"budget_spent_total_eur": 0.0,
"shield_mode": "on",
"allowed_residencies": ["DE", "EU"],
"require_no_cloud_act": true,
"require_section203": true,
"last_used_at": null
}With multiple tags on a request, allowed models and providers use the strict intersection (403 model_not_allowed_for_tag / provider_not_allowed_for_tag), any “on” in shield_mode wins over “off”, and the full request cost is booked to the API key and to every attached tag.
| Method & path | Behaviour (can_manage_tags required) |
|---|---|
GET /v1/tags | Lists your organisation’s tags (optionally filtered with limit, offset and search query q). |
POST /v1/tags | Creates a new tag (201 Created); returns 409 tag_already_exists if the name is already taken. |
GET | PUT /v1/tags/_default | Reads or updates the default tag template (tag_auto_create_enabled, shield_mode, budget, model and provider restrictions). |
GET | PUT | PATCH /v1/tags/{name} | Reads, creates/replaces or updates a single tag; budget_spent_eur, budget_spent_total_eur and last_used_at are preserved across PUT and PATCH. |
DELETE /v1/tags/{name} | Two-stage (204 No Content): on an active tag (is_active: true), the first call sets is_active: false (subsequent requests get 403 tag_disabled; reactivate via PATCH with {"is_active": true}). On an already inactive tag, a second call deletes it permanently if budget_spent_total_eur == 0 – otherwise 409 tag_has_spend_history. |
Credit, starter credit and top-up.
Organisations not billed by invoice pay for managed model calls (status < 400) and Noirdoc Shield inspections from prepaid credit (Billing → Top up via Mollie by card or SEPA bank transfer in whole euros, credited after 1–2 banking days for bank transfers, plus VAT where applicable). Because actual usage is deducted after the response, the balance can dip below zero and is settled automatically on the next top-up:
| Area | Rules |
|---|---|
| Billing units | Chat, Responses, Messages: input, output and cache tokens (count_tokens / input_tokens cost €0). Embeddings: input tokens. Rerank: input tokens or per request. /v1/audio/speech: input characters. /v1/audio/transcriptions: provider-reported audio duration pro rata per minute. /v1/images/generations: per image or megapixel. Shield: +€0.40 per 1M inspected input tokens (BYOK without active Shield remains €0). |
| Starter credit | Granted once per account on the first organisation created. Until the first top-up is confirmed, managed routes allow only starter-eligible models (403 starter_model_not_allowed, marked After top-up in the portal, free of charge and not counted against rate limits) and cap managed requests across the organisation to 5 requests/minute and 25 requests/day (UTC) (429 starter_rate_limit_exceeded with Retry-After; minute rejections do not count towards the daily 25). BYOK routes are unrestricted; the first confirmed top-up unlocks the full catalogue and lifts both limits immediately. |
| Automatic top-up | Card-only (Card payment → Top up automatically when credit runs low with card-charge authorisation). Three required fields: Top up below (threshold), Amount per top-up (>= threshold) and At most per month (calendar month cap in Europe/Berlin, >= amount per top-up; manual top-ups excluded, daily card limit applies to new organisations). At most one automatic charge runs at a time; admins receive mandatory receipt emails. |
| Pause & card replacement | After a bank decline, automatic top-up pauses and can be resumed under Billing via Reactivate. For an expired card (Save a new card), an invalid billing profile, or after Switch off / Remove card, make one fresh card top-up; for chargebacks or blocked top-ups, contact hello@noirdoc.de. |
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request_tags | The X-Noirdoc-Tags header or the tag name in the path under /v1/tags is empty, contains more than 5 tags or does not match the format ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$. |
| 401 | invalid_api_key | The key is missing, invalid or deactivated, or the organisation is not active. |
| 402 | insufficient_credit | The organisation's credit is used up or lower than the estimated maximum cost of the request (including Noirdoc Shield, also on BYOK routes when Shield is active). |
| 402 | key_budget_exhausted | This key's budget is used up for the current period or does not cover the estimated cost of the request. |
| 402 | tag_budget_exhausted | The budget of a tag named in X-Noirdoc-Tags is used up for the current period or does not cover the estimated cost of the request; message names the tag. |
| 403 | starter_model_not_allowed | The organisation is still using only its starter credit, and the model or its managed provider is not included in starter credit. |
| 403 | model_not_billable | The model has no complete price on record, so it cannot be used with credit. |
| 403 | request_tags_disabled | The request sends X-Noirdoc-Tags or calls /v1/tags, but request tags (Preview) are not enabled for this organisation. |
| 403 | tag_not_found | The named tag does not exist. On requests with X-Noirdoc-Tags, automatic tag creation is turned off (status code 403); on /v1/tags/{name}, the gateway answers with status code 404. |
| 403 | tag_disabled | A tag named in X-Noirdoc-Tags is deactivated. |
| 403 | tag_limit_exceeded | The organisation has reached the maximum of 1,000 request tags. |
| 403 | insufficient_key_permissions | The API key lacks permission for /v1/tags (can_manage_tags) or /v1/shield/policy (can_manage_shield), a key pinned to shield_mode: on tries to weaken the Shield policy or a tag's shield_mode, or the tag requests broader models, providers or compliance rules than the calling key itself holds. |
| 403 | model_not_allowed_for_tag | The model is not one of the allowed models of a tag named in X-Noirdoc-Tags. |
| 403 | provider_not_allowed_for_tag | The restrictions of a tag named in X-Noirdoc-Tags (providers, data residency, CLOUD Act, § 203) exclude every provider of this model. |
| 409 | tag_already_exists | A tag with this name already exists in the organisation. |
| 409 | tag_has_spend_history | Spend has already been recorded for this tag, so it cannot be permanently deleted. |
| 429 | starter_rate_limit_exceeded | The organisation is still using only its starter credit and has reached the limit of 5 requests per minute or 25 requests per day (UTC) for managed providers. The response contains Retry-After with the wait in seconds. |
Models and pricing via API.
GET https://api.noirdoc.de/v1/models
Returns, sorted by id, every model ID the calling key may invoke after applying § 203 StGB, starter credit, key rules and optional X-Noirdoc-Tags (own BYOK routes take precedence over managed routes; calling the wrong endpoint family or API format returns 400 wrong_endpoint_for_model):
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
for model in client.models.list():
print(model.id, model.owned_by)import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
for await (const model of client.models.list()) {
console.log(model.id, model.owned_by);
}curl https://api.noirdoc.de/v1/models \
-H "Authorization: Bearer $NOIRDOC_API_KEY"{
"object": "list",
"data": [
{
"id": "qwen3.8-27b",
"object": "model",
"owned_by": "platform",
"display_name": "Qwen 3.8 27B",
"endpoint_family": "chat",
"legacy_public_id": null
}
]
}owned_by distinguishes your own BYOK routes (“personal”) from managed routes (“platform”); endpoint_family is “chat”, “embeddings”, “rerank”, “stt”, “tts” or “image_gen” (non-model endpoints such as /v1/shield, /v1/files, /v1/skills and /v1/tags do not appear).
GET https://api.noirdoc.de/v1/prices
Public endpoint requiring no authentication: lists every active managed route with a complete price (one row per model and provider, never BYOK) including starter_allowed, alongside the top-level flat rate for Noirdoc Shield:
import httpx
payload = httpx.get("https://api.noirdoc.de/v1/prices").json()
prices = payload["data"]
shield_price = payload["shield"]const res = await fetch("https://api.noirdoc.de/v1/prices");
const { data: prices, shield: shieldPrice } = await res.json();curl https://api.noirdoc.de/v1/prices{
"object": "list",
"data": [
{
"public_id": "qwen3.8-27b",
"legacy_public_id": null,
"provider_slug": "aki-io",
"provider_display_name": "AKI.IO",
"endpoint_family": "chat",
"price_input": 0.3,
"price_output": 2.2,
"price_cache_read": null,
"price_cache_write": null,
"price_cache_write_1h": null,
"long_context_threshold": null,
"price_input_long": null,
"price_output_long": null,
"price_cache_read_long": null,
"price_cache_write_long": null,
"price_unit": "per1MTokens",
"price_currency": "EUR",
"starter_allowed": true
}
],
"shield": {
"price_input": "0.40",
"price_unit": "per1MTokens",
"currency": "EUR",
"price_currency": "EUR"
}
}Example figures illustrate the response format; query the endpoint directly for current euro prices (including prompt cache rates and long-context tiers above long_context_threshold).
price_unit | Meaning | Endpoint family & populated price fields |
|---|---|---|
per1MTokens | per 1M tokens | Chat (price_input, price_output, optional cache & *_long), embeddings, rerank and Noirdoc Shield (price_input) |
per1MChars | per 1M input characters | Speech output tts (price_input) |
perRequest | per successful request (regardless of document count) | Rerank (price_input) |
perMinute | per minute of audio (charged pro rata) | Transcription stt (price_input or price_output) |
perImage | per generated image | Images image_gen (price_output) |
perMpx | per started megapixel (1024 × 1024 pixels) per image | Images image_gen (price_output) |
perFirstMpx | first megapixel in price_output; each additional megapixel optionally in price_input | Images image_gen (price_output, optional price_input) |