API keys
API keys are the credentials applications use to authenticate against a consumer.
An API key is the credential an application uses to call a consumer. Every request to a consumer's endpoints, whether query, chat, or MCP, carries an API key, and the key decides which consumer the caller is allowed to reach.
How API keys work
An API key is issued for one consumer. When a request arrives, Gaur checks the key, resolves it to its consumer, and applies that consumer's scope: the caller can only reach the contracts that consumer exposes, and only through the protocols it has enabled.
Callers present the key as a Bearer token:
curl -X POST https://<your-gaur-host>/v1/api/<consumer_slug>/query \
-H "Authorization: Bearer <api_key>" \
-H "Content-Type: application/json" \
-d '{ "contract_name": "daily_revenue", "query": { "measures": ["revenue"] } }'See Authentication for the integrator's view.
Key metadata and auth context
When you create a key, you can attach metadata to it. Part of that metadata becomes the key's auth context: fixed values that travel with every request the key makes and that the caller can't change.
This is how you bake scoping into a credential. Issue one key per partner with
that partner's org_id in its metadata, and every request that key makes is
automatically scoped to that organization. A contract's
row-level security
reads those values as auth context.
Use key metadata for scope that's a property of the credential itself. For scope that changes per request, like the current end user in a multi-user app, use request context instead. The RLS section covers the difference in full.
Issuing a key
Choose the consumer
A key belongs to a consumer. Pick the consumer whose contracts the integration should reach.
Create the key
Generate the key, give it a clear name that identifies who or what will use it
(like mobile-app-prod or partner-acme), and set any metadata it needs.
Copy the secret immediately
The key's secret value is shown once, at creation. Copy it into your secret manager right away. If it's lost, revoke the key and issue a new one.
Managing keys
- List the keys for a consumer to see what's in use.
- Revoke a key to immediately stop it from authenticating. Revocation can't be undone; issue a new key to restore access.
A key has a status, so a revoked key stays visible for audit purposes without being usable.
Good practice
- One key per integration. Give each application or partner its own key. When you rotate or revoke, only that one integration is affected.
- Scope through consumers. A key inherits its consumer's scope. To give an integration a different set of contracts, point it at a different consumer rather than widening an existing one.
- Treat keys as secrets. Store them in a secret manager, never in source control, client-side code, or logs. A key is a Bearer credential: anyone who has it can call the consumer.
- Rotate periodically. Issue a replacement key, move the integration over, then revoke the old one.
- Revoke on exposure. If a key might have leaked, revoke it immediately and issue a new one.