Get started

Authentication

Every call except the price list carries a bearer credential in the Authorization header. Your code uses an API key; an AI assistant connecting over MCP signs in with OAuth or uses an API key.

API keys

Authorization: Bearer sk_live_3f9a...

• A key belongs to an organisation, not to a person. Searches made with it are charged to the organisation's wallet and appear in its usage.
• Create keys on the dashboard's API keys page, or with POST /api/v1/api-keys using an existing key. The secret is returned once; TRIVDA stores only an argon2 hash and a 12-character display prefix (sk_live_ plus 4 characters).
• List keys with GET /api/v1/api-keys and revoke one with DELETE /api/v1/api-keys/{key_id}. A revoked key fails at once with 401.
• GET /api/v1/api-keys/current returns the organisation, key prefix, name and scopes of the credential you call it with, and whether it is a sandbox key.
• Use keys from servers only. A key in browser code or a mobile app can be read and spent by anyone.

Sandbox keys

A sandbox key starts with sk_test_. It reaches the same routes as a live key but gets deterministic synthetic data, never your organisation's or a partner's, and it is never charged. Every response carries the header X-Sandbox: true and "sandbox": true in its JSON body.

• Create one on the API keys page with the Sandbox key switch, or with POST /api/v1/api-keys and "sandbox": true.
• The two kinds cannot be mixed up: a live key never gets sandbox answers, and a sandbox key never reaches real data, the wallet or key management (creating or revoking a key with it is refused with 403).
• Switching from sandbox to live is changing the key. The SDKs and CLI page describes the synthetic data.

curl -sS "$TRIVDA_URL/api/v1/api-keys" \
  -H "Authorization: Bearer $TRIVDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "local development", "sandbox": true}'

Scopes

A key can be narrowed when it is created. Scopes are a list of strings; an empty list means everything the organisation may do.

curl -sS "$TRIVDA_URL/api/v1/api-keys" \
  -H "Authorization: Bearer $TRIVDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "chatbot backend", "scopes": ["use_case:rag"]}'

Rules that keep scopes safe:

• A scoped key can only create keys with a subset of its own scopes. With an empty list, the new key inherits the creator's scopes; it never widens to the whole organisation.
• A search outside a key's scopes is refused with 403 before anything runs or is charged.
• Other prefix: forms are refused with 422, so a typo never becomes an inert scope.

OAuth for MCP clients

Assistants such as Claude and ChatGPT connect to https://13-63-0-55.sslip.io/connector/mcp and sign in with OAuth 2.1. You do not configure anything: the client discovers what it needs from the server.

1. The client calls the connector without a token and gets 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/connector/mcp.
2. That metadata names the authorisation server, which is TRIVDA itself (/.well-known/oauth-authorization-server).
3. The client registers itself (dynamic client registration) and sends you to a TRIVDA consent page with PKCE. You sign in and approve.
4. The client receives an access token that lasts 1 hour and, if it asked for one, a refresh token. Refresh tokens are single-use and rotate; reusing an old one revokes the whole chain.

• Only the published redirect addresses of known assistants (Claude, ChatGPT, Cursor, VS Code) and loopback addresses for desktop clients are accepted. The consent page always shows where you will be sent.
• A token holds only while you are a member of its organisation. Removing a member, the organisation or the user revokes their connector tokens.
• Connector searches are charged to the same organisation wallet as API searches.

Clients that let you set a header can skip OAuth and send an API key instead: Authorization: Bearer sk_live_.... The MCP page shows both for each client.

Machine-to-machine tokens

For a service that should not hold a long-lived key, TRIVDA can issue an OAuth 2.0 client (a client_id and client_secret) that is exchanged for a short-lived bearer token with the client_credentials grant. These clients are issued on request; ask TRIVDA if you need one. The token is used exactly like an API key.

When authentication fails