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

# Autenticação

> Como autenticar na API pública da VMArea usando tokens de API.

A API pública da VMArea usa exclusivamente tokens de API. Não há fluxo OAuth, cookie de sessão nem JWT para acesso público à API.

## Formato do token

Todos os tokens começam com o prefixo `vmk_`. Passe o token no cabeçalho `x-api-key`:

```
x-api-key: vmk_...
```

## Como obter um token

Os tokens são criados no [painel da VMArea](https://vmarea.com/dashboard/settings/api-keys):

<Steps>
  <Step title="Acesse API Keys">
    Navegue até **Configurações → API Keys**.
  </Step>

  <Step title="Crie uma nova chave">
    Clique em **New API Key**.
  </Step>

  <Step title="Nomeie e configure">
    Dê um nome descritivo à chave (ex.: `deploy-pipeline`).
  </Step>

  <Step title="Selecione os escopos">
    Escolha os [escopos](/pt/scopes) necessários — conceda apenas o que for preciso.
  </Step>

  <Step title="Defina validade (opcional)">
    Tokens sem validade permanecem ativos até serem revogados manualmente.
  </Step>

  <Step title="Copie o segredo">
    Clique em **Create**. **Copie o segredo imediatamente** — ele é exibido apenas uma vez e não pode ser recuperado depois.
  </Step>
</Steps>

## Ciclo de vida do token

```
Criado → Em uso → [Expirado | Revogado]
```

* Um token fica ativo a partir do momento da criação.
* Se uma validade foi definida, o token é rejeitado automaticamente após essa data/hora.
* Você pode revogar qualquer token pelo painel a qualquer momento.
* Excluir um token é permanente; requisições que o usarem receberão `401 Unauthorized`.

## Escopos

Os tokens carregam apenas as permissões concedidas na criação. Uma requisição que exige um escopo que o token não possui retorna `403 Forbidden`. Veja [Escopos e permissões](/pt/scopes) para a lista completa.

## Exemplos de uso

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.vmarea.com/api/public/v1/vms \
    -H "x-api-key: $VMAREA_TOKEN"
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.vmarea.com/api/public/v1/vms", {
    headers: { "x-api-key": process.env.VMAREA_TOKEN },
  });
  ```
</CodeGroup>

## Boas práticas de segurança

<Warning>
  Nunca versione tokens no controle de código-fonte. Use variáveis de ambiente ou um gerenciador de segredos.
</Warning>

* **Use o conjunto mínimo de escopos** necessário para a integração.
* **Faça rotação de tokens regularmente**, especialmente após qualquer suspeita de exposição.
* **Defina validade** para tokens usados em ambientes de CI/CD.
* Trate seu token `vmk_` com o mesmo cuidado que uma senha.