Authentication

Every request to a Gaur consumer is authenticated with an API key, passed as a Bearer token. This page covers how to use a key from a consuming application.

The Bearer token

Send your API key in the Authorization header on every request:

Authorization: Bearer <api_key>

A complete request:

curl -X POST https://<base-url>/v1/api/<consumer_slug>/query \
  -H "Authorization: Bearer gaur_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "contract_name": "daily_revenue", "query": { "measures": ["revenue"] } }'

What a key grants

An API key is issued for one consumer. The key determines:

• Which consumer you can call. A key only authorizes the consumer it was issued for. Calling a different consumer's path with it returns 403.
• Which contracts you can reach: only the contracts that consumer is scoped to.
• Which protocols you can use: the REST query API, chat completions API, and/or MCP server, depending on what the consumer has enabled.

You don't configure scope on the key itself. Scope comes from the consumer. To get access to a different set of contracts, you're given a key for a different consumer.

Keys and row-level security

A key can also carry metadata that a contract's row-level security uses as auth context. These are fixed values, set when the key was created, that scope every request the key makes. You don't send them; they travel with the key. If your integration needs to scope data per end user instead, you send request context on each call. See Querying contracts.

Getting a key

API keys are created by a builder in the Gaur app. See API keys. When a key is created, its secret value is shown once. Whoever provisions your integration has to copy it at that moment and deliver it to you securely.

Handling keys safely

• Store keys in a secret manager. Never commit a key to source control or ship it in client-side code. A key is a Bearer credential: anyone who has it can call the consumer as you.
• Keep keys server-side. Call Gaur from your backend, not directly from a browser or mobile client where the key would be exposed.
• Use a distinct key per environment. Separate keys for development, staging, and production limit the damage if one leaks.
• Rotate and revoke. If a key might be exposed, ask for it to be revoked and replaced. Revocation takes effect immediately.

Authentication failures

Every error response carries { "message": string, "code": string, "errors": string[] | null }. Branch your logic on code, not on message.

Next