> ## 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.

# Autenticação

> Autentique as requisições da API da YCloud com uma chave de API.

## O que é

A YCloud usa chaves de API para identificar sua conta e autorizar requisições à API. Envie a chave apenas a partir de código confiável no lado do servidor.

## Antes de começar

Crie ou obtenha uma chave de API na sua conta YCloud. Decida onde cada ambiente armazenará seu segredo antes de adicionar a chave ao código da aplicação.

## Requisição

Envie a chave no cabeçalho `X-API-Key` em todas as requisições.

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

Não adicione o prefixo `Bearer`. O valor do cabeçalho é a própria chave de API.

## Resposta

Credenciais válidas permitem que o endpoint retorne sua resposta de sucesso normal. Credenciais inválidas ou não autorizadas retornam uma resposta de erro `4xx`.

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

## Armazene as chaves com segurança

* Mantenha as chaves de API em um gerenciador de segredos ou em uma variável de ambiente criptografada.
* Use chaves de API apenas em código confiável no lado do servidor.
* Nunca insira uma chave em uma URL, pacote do navegador, aplicativo móvel, log ou captura de tela.
* Use chaves separadas para ambientes separados quando a configuração da sua conta permitir.
* Faça a rotação de uma chave imediatamente se você suspeitar que ela foi exposta.

Para o desenvolvimento local, exporte a chave no seu shell:

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

Leia-a do ambiente na sua aplicação. Não a insira diretamente no código.

## Rotacionar uma chave

Crie ou selecione a chave substituta, faça o deploy dela em todos os serviços que chamam a YCloud, verifique o tráfego com a nova chave e, em seguida, revogue a chave antiga. Se suspeitar de exposição, faça a rotação primeiro e investigue depois.

## Solução de problemas de autenticação

Uma falha de autenticação retorna uma resposta `4xx`. Verifique se:

* A requisição usa `https://api.ycloud.com/v2`.
* O nome do cabeçalho é exatamente `X-API-Key`.
* A chave não contém espaços extras nem aspas.
* A chave está ativa e pertence à conta YCloud desejada.
* A conta tem acesso ao produto usado pelo endpoint.

Registre o `requestId` da resposta nos logs para solução de problemas, mas nunca registre a chave de API. Consulte [Erros](/pt/api-reference/guides/api-fundamentals/handle-errors) para saber o formato da resposta.

<Card title="Testar autenticação" icon="rocket" href="/pt/api-reference/getting-started/quickstart">
  Verifique uma chave com uma requisição somente leitura à API Balance.
</Card>


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