API keys for technical users

An API key is the simplest way to connect a script, a CI job, a service or a desktop client to Mandatum. Use OAuth instead when a person is connecting an app they use interactively, because OAuth lets them approve and revoke it without seeing a secret.

Audience: developers, system integrators and automated systems.

Choosing between a key and OAuth #

Creating a key #

1. Sign in and open the workspace's API keys page, /w/<workspace>/settings/integrations. Only owners and admins can create keys. Other members see a read-only list.
2. Enter a name, such as ci-nightly.
3. Choose the expiry: 30 days, 90 days (the default), 1 year, or never. A key past its expiry is refused with 401.
4. Choose Create Key. The secret starts with mdt_live_ in production and mdt_test_ elsewhere. It is shown once. Copy it now.
5. Under Sharing Controls, switch on the scopes the key needs. See Scopes and sharing. A key with no scopes sees no tools.

The key list shows each key's name, expiry, scopes and Last used date.

Using a key #

Send it as a bearer token:

curl "https://mandatum.intergentech.ai/api/v1/statutes/search?query=companies&jurisdiction=BB" \
  -H "Authorization: Bearer $MANDATUM_API_KEY"

To connect an MCP client, give it the endpoint https://mandatum.intergentech.ai/api/mcp and set the key as a bearer token in its configuration. Client configuration formats differ, so follow the client's own documentation for remote MCP servers with bearer authentication. The connect guides show two working examples.

Data egress #

Statute text, search results and the other data a tool returns are sent to whatever client receives the response. If you connect a third-party model or service with a key, that service receives the data. Before you connect one, read Data egress, and check it against your own data-handling obligations.

Use scopes to limit what a key can return. A key with only citation:verify returns citation verdicts and nothing else. Matters are off by default and are a separate, explicit scope.

Rotating and revoking #

• Rotate revokes the key and issues a new secret with the same name, scopes and expiry. The old secret stops working at once.
• Revoke stops the key at once. Its next request gets 401.

Owners and admins do both from the API keys page. A key also stops working when its owner is removed from the workspace. For the full lifecycle, read Authentication.

Keeping keys safe #

• Store keys in environment variables or a secrets manager, never in source code or in a shared chat.
• Use one key per integration and per environment, so you can revoke one without breaking the rest.
• Rotate keys on a schedule, and whenever someone who knew a key leaves the team.
• Check Last used on the key list. A date you do not expect is a reason to rotate.