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

# Authentication

> Authenticate YCloud API requests with an API key.

## What it is

YCloud uses API keys to identify your account and authorize API requests. Send
the key only from trusted server-side code.

## Before you begin

Create or retrieve an API key in your YCloud account. Decide where each
environment will store its secret before you add the key to application code.

## Request

Send the key in the `X-API-Key` header on every request.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.ycloud.com/v2/balance \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

Do not add a `Bearer` prefix. The header value is the API key itself.

## Response

Valid credentials allow the endpoint to return its normal success response.
Invalid or unauthorized credentials return a `4xx` error response.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 401,
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "requestId": "req_1KjtKI80IKoaJNa6n6p"
  }
}
```

## Store keys securely

* Keep API keys in a secret manager or an encrypted environment variable.
* Use API keys only in trusted server-side code.
* Never place a key in a URL, browser bundle, mobile application, log, or screenshot.
* Use separate keys for separate environments when your account setup allows it.
* Rotate a key immediately if you believe it has been exposed.

For local development, export the key in your shell:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export YCLOUD_API_KEY="YOUR_API_KEY"
```

Read it from the environment in your application. Do not hard-code it.

## Rotate a key

Create or select the replacement key, deploy it to every service that calls
YCloud, verify traffic with the new key, and then revoke the old key. If you
suspect exposure, rotate first and investigate afterward.

## Troubleshoot authentication

An authentication failure returns a `4xx` response. Check that:

* The request uses `https://api.ycloud.com/v2`.
* The header name is exactly `X-API-Key`.
* The key does not contain extra spaces or quotation marks.
* The key is active and belongs to the intended YCloud account.
* The account can access the product used by the endpoint.

Log the response `requestId` for troubleshooting, but never log the API key. See [Errors](/en/api-reference/guides/api-fundamentals/handle-errors) for the response format.

<Card title="Test authentication" icon="rocket" href="/en/api-reference/getting-started/quickstart">
  Verify a key with a read-only Balance API request.
</Card>


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