> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & credentials

> Authenticate server-to-server AvraAPI requests with project-scoped credentials and an environment boundary.

AvraAPI provider and UPG server APIs authenticate a request using a project Client ID, Client Secret, and environment selector.

## Required headers

```http theme={null}
X-API-KEY: your_project_client_id
X-API-SECRET: your_project_client_secret
X-ENV: development
Accept: application/json
```

| Header | Purpose |
| - | - |
| `X-API-KEY` | Identifies the project credential. |
| `X-API-SECRET` | Proves possession of the secret. Send it only from your server. |
| `X-ENV` | Selects the credential’s project environment. Use `dev` or `development` for Development; use `prod` or `production` only from your production integration. |

When `X-ENV` is omitted, the API treats the request as Development. The credential is still checked against that environment boundary.

## Store secrets safely

<Tabs>
  <Tab title="Recommended">
    Use an environment variable or a managed secret store in your backend. Limit access to the process that makes AvraAPI requests.
  </Tab>

  <Tab title="Never do this">
    Do not put Client Secrets in a browser bundle, a public Git repository, a mobile app, URL query string, analytics event, support ticket, or screenshot.
  </Tab>
</Tabs>

```ini theme={null}
# Server-side environment configuration only
AVRAAPI_CLIENT_ID=your_development_client_id
AVRAAPI_CLIENT_SECRET=your_development_client_secret
AVRAAPI_ENV=development
```

## Generate and rotate credentials

The dashboard shows a full Client Secret only when it is generated or rotated. If it is lost or exposed, rotate it immediately and update every affected server deployment.

<Warning>
  Rotating a credential invalidates the previous secret. Plan a controlled deployment so your running application receives the replacement before the old credential is removed from use.
</Warning>

## Authentication failures

Missing, inactive, mismatched, or invalid credentials produce an `unauthorized` error. Paused projects return `project_paused` and should be handled as an operational state rather than retried continuously.

```json theme={null}
{
  "success": false,
  "request_id": "2da44813-ec46-4dde-b403-6a371543e2b9",
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key or environment."
  },
  "meta": {
    "provider_override": null
  }
}
```

See [API key safety](/security/api-key-safety) for incident-response guidance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.