Keys

An AI company’s systems authenticate with retrieval keys, never a bearer token or an API key string. You make the key pair; you register the public half; every request your systems send is signed with the private half (Signing requests). There is no secret for MasterDB to hold, leak or reset.

Making a key

Ed25519 is the default; P-256 (ES256) is also accepted. Make the key where it will be used — a secrets manager, an HSM, or the host itself:

openssl genpkey -algorithm ed25519 -out retrieval-key.pem
openssl pkey -in retrieval-key.pem -pubout -out retrieval-key.pub.pem

The CLI’s masterdb keygen also makes keys, marked as test keys; use them in the sandbox only.

Registering it

In the AI Portal, a person with the integration_manager role, signed in with a passkey, registers the public half as a JWK, with a label ("us-east inference fleet", say). The answer names the key’s id — the RFC 7638 thumbprint of the public JWK — which your requests carry as keyid.

• A key belongs to one legal entity of your company, and through it to your AI group. Every request resolves to (ai_company_uuid, ai_group_id) from the key alone; any identifier in a body, query or header is ignored.
• Every region holds the new key within seconds. A key a region does not hold is refused (key_unknown); it is never looked up on the request path.
• A production key is issued only to a verified AI company whose owner has accepted the AI-company Terms version in force. When a new version comes into force, the keys already issued keep working, but the next key — registered or rotated in — waits until the new version is accepted: until then the answer is agreement_required (403). The certificate is issued the same way: once the Terms are accepted.
• A sandbox key is taken in the same AI Portal, as a separate kind of key, and needs neither verification nor the Terms (The sandbox). The answer carries a sandbox_key_grant (mdb_sbxk1.…), MasterDB’s signed statement of the key and your company, which holds no secret. Send it as the MDB-Sandbox-Key header on your sandbox requests: the first request that carries it registers the key in the sandbox’s own key register, and without it that first request is refused key_unknown (401). The TypeScript SDK sends it for you (createRetrievalClient({ …, sandboxKeyGrant })), and so does the Python signing helper (MasterDBAuth(key, sandbox_key_grant=grant)) and the CLI (masterdb verify --url … --sandbox-key-grant GRANT). A key revoked in the portal stops working in the sandbox within about a minute, grant or not. Production never holds a sandbox key and ignores the header.

A company that already publishes a key directory at /.well-known/http-message-signatures-directory can ask for its keys to be imported from there instead of pasting them; the import is an audited job that pins each key’s thumbprint and re-checks the directory daily. Nothing is ever fetched from your directory while a request is being answered.

Rotating

Rotation is overlap: register the new key, move your systems to it, then revoke the old one. Both are valid in between, and your usage shows traffic per key, so you can see when the old one has gone quiet. The portal’s rotate action does the register-then-revoke in one step.

Revoking

Revocation takes effect in every region within seconds and fails closed: a revoked key is removed from the region’s memory, and a key that is not in memory is refused. If a key may be compromised, revoke it at once; a stolen key’s requests are billed to its owner until then, and the receipts and your own reconciliation show them.

What a key is not

• Not an account. Anyone holding the private half can sign as your company, so keep it where your inference runs and nowhere else.
• Not shared with MasterDB. MasterDB stores the public half only.
• Not reusable across environments. A sandbox key never works in production.