Concepts
Organisation & keys
How organisation, members and API keys relate and which settings apply to the whole organisation or to a single key.
The organisation is the unit the gateway works for. It owns the API keys, its own providers, the settings and the credit. People access them through the portal as members of an organisation.
Members and roles
Every member has one of two roles. The roles are listed under Members; only admins can change them.
| Role | Permissions |
|---|---|
| Admin | Invite and remove members, change roles, create and revoke keys, connect own providers (BYOK), change settings, top up credit |
| Member | View keys, usage, settings and balance |
A person can be a member of several organisations. The role applies per organisation.
API keys
An API key belongs to the organisation, not to the person who created it. Admins of your organisation create keys under Models → API keys with New key.
- Every key starts with
px-. - The portal shows the full key only once, right after it is created. Store it in a safe place straight away.
- A revoked key stops working immediately. The gateway then answers with status code 401. You can reactivate a revoked key or delete it permanently.
Every request to the gateway runs through a key. Through it, the gateway recognises the organisation and applies its settings. How to send the key is described under Authentication & headers.
Organisation settings
These settings apply to all keys of the organisation:
| Setting | Effect | Where in the portal |
|---|---|---|
| Shield default setting | Defines the default policy for Noirdoc Shield (default_off, default_on, enforced) and whether keys, request tags or the X-Noirdoc-Shield header may override it. | Models → Shield |
| Protection filters & custom blocklist | Controls the five protection filters (secrets, pii, ner, injection, custom as off, redact or block) and the custom blocklist. See Noirdoc Shield. | Models → Shield |
| Allow Responses API storage at provider | Allows managed providers to store input and response after answering (allow_stored_responses; Responses API store, previous_response_id). New organisations: off. See Responses. | Models → Shield (Advanced Settings) |
| Allow file and image attachments in requests | Allows messages with file, image or audio parts as well as calls to /v1/files, /v1/skills and /v1/audio/transcriptions (allow_file_content). Default: on. See Files. | Models → Shield (Advanced Settings) |
| Own providers (BYOK) | Your organisation’s provider keys for an OpenAI- or Anthropic-compatible provider. For their model IDs they take precedence over the providers managed by Noirdoc. See Providers & routing. | Models → Providers |
| Professionals bound by secrecy | Limits managed providers to those marked as covered under § 203 German Criminal Code (StGB). See Professional secrecy. | Question on § 203 StGB on Getting started |
| Credit | Balance from which the gateway deducts usage. See Credit & billing. | Billing |
Legacy masking settings such as mapping TTL and file analysis mode apply only to pre-existing organisations during the transition period until 30.11.2026 (see Legacy masking).
Settings per key
These settings apply to a single key only. Without a value, there is no restriction.
| Setting | Effect |
|---|---|
| Allowed models | The key can call only these models. The gateway rejects other model IDs with model_not_allowed_for_key. |
| Restrictions | Allowed providers, data residency, only providers without CLOUD Act exposure, only providers that cover § 203 StGB. The gateway leaves out providers that do not meet a restriction. |
| Noirdoc Shield | Controls Shield per key (inherit Inherit, on On, off Off). Takes precedence over request tags, header and organisation default; an enforced organisation policy cannot be switched off. See Policy and precedence. |
| Budget | Spending limit in euros, optionally reset daily, weekly or monthly. It counts usage through managed providers as well as the Noirdoc Shield inspection fee (including on BYOK routes when Shield is active). Once it is reached, the gateway answers with key_budget_exhausted. |
| Manage Shield policy via API | Allows the key (can_manage_shield) to read and update the organisation’s Shield policy via /v1/shield/policy. A key pinned to on cannot weaken the policy. |
Tag management (/v1/tags) | Allows the key (can_manage_tags) to create and update request tags and the default tag template via /v1/tags (within the key’s own model, provider and Shield restrictions). |
GET /v1/models takes allowed models and restrictions into account: the list contains only models the calling key may use.
The steps in the portal are shown in Restrict models & providers, Set up Noirdoc Shield and Budgets per key.
Request tags (Preview)
In organisations that have request tags (Preview) enabled, you can also configure budgets, allowed models, provider restrictions and the Noirdoc Shield mode (shield_mode) per matter, cost centre or team under Models → Tags. Your application passes the tag name or names in the X-Noirdoc-Tags header without creating a separate API key for every matter. Setup and management via /v1/tags are described in Request tags (Preview).