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

# Authenticate API Requests with Varo Cloud API Keys

> Generate and manage API keys for the Varo Cloud REST API. Learn how to pass your key in requests and handle authentication errors.

Varo Cloud uses API key authentication to secure all requests to the REST API. Every call you make to `https://inference.varo.cloud/v1` must include a valid API key in the `Authorization` header using the Bearer token scheme. Without a properly formatted key, requests are rejected before they reach any resource endpoint.

## Generate an API key

You can create as many API keys as your plan allows. To generate a new key:

1. Open the [Varo Cloud dashboard](https://varo.cloud/auth) and sign in to your account.
2. Navigate to **Settings → API Keys** in the sidebar.
3. Click **New API Key**.
4. Enter a descriptive name for the key (for example, `ci-pipeline-prod` or `monitoring-service`).
5. Click **Create** and immediately copy the key that appears.

<Warning>
  You will only see the full key once. Store it in a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform's encrypted environment variables. There is no way to retrieve the key value after you close this dialog.
</Warning>

## Using your API key

Pass your API key in the `Authorization` header of every request. The header value must follow the format `Bearer YOUR_API_KEY`.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://inference.varo.cloud/v1/projects \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://inference.varo.cloud/v1/projects', {
    headers: {
      'Authorization': `Bearer ${process.env.VARO_API_KEY}`
    }
  });
  const data = await response.json();
  ```
</CodeGroup>

Reading the key from an environment variable (as shown in the JavaScript example) is strongly recommended. Avoid hardcoding key values directly in source code or committing them to version control.

## API key scopes

All API keys generated in Varo Cloud are scoped to your organization. A key has read and write access to every resource within your organization, including projects, deployments, environments, and team members.

Because keys carry broad permissions, the best practice is to create a dedicated key for each application or integration rather than sharing a single key:

* Create one key per CI/CD pipeline (for example, separate keys for your staging pipeline and production pipeline).
* Create separate keys for third-party integrations so you can revoke access to a single integration without affecting others.
* Name each key clearly so you can identify its purpose at a glance in the API Keys list.

## Rotate and revoke keys

If a key is compromised or you need to cycle credentials as part of your security policy, you can rotate or revoke it at any time from **Settings → API Keys**. Click the **•••** menu next to the key you want to manage and choose either **Rotate** or **Revoke**.

* **Rotate** — Immediately invalidates the existing key and generates a replacement. Update your applications with the new key as quickly as possible.
* **Revoke** — Permanently deletes the key with no replacement. The key cannot be recovered.

<Note>
  Revoking a key immediately invalidates it. Update your applications before revoking to avoid service interruptions caused by failed authentication.
</Note>

## Authentication errors

When a request fails due to an authentication or authorization issue, the API returns a JSON error body alongside an HTTP status code. The table below describes the most common authentication-related errors.

| Status | Code           | Meaning                                                                                          |
| ------ | -------------- | ------------------------------------------------------------------------------------------------ |
| `401`  | `unauthorized` | The API key is missing, malformed, or no longer valid.                                           |
| `403`  | `forbidden`    | The API key is valid but does not have permission to access the requested resource.              |
| `429`  | `rate_limited` | Your key has exceeded the allowed request rate. Wait before retrying or review your plan limits. |

All error responses follow a consistent JSON envelope:

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "No valid API key provided.",
    "status": 401
  }
}
```

Use the `code` field in your error handling logic to distinguish between authentication failures and business-logic errors.