---
title: "Autenticação"
description: "Toda chamada leva uma chave de API no header Authorization."
source_url: "https://hypio.doti.gg/docs/autenticacao"
updated: "2026-11-11"
---

# Autenticação

Toda chamada leva uma chave de API no header Authorization.

## Enviar a chave

```http
Authorization: Bearer $HYPIO_API_KEY
```

Só o header `Authorization` vale. Chave na query string vaza em log, em Referer e no histórico, e a API recusa.

## Chaves

- Começam com `dsk_`. Guardamos só o hash: a chave aparece uma vez, na criação.
- Até 10 chaves ativas por organização.
- Expiram em 90 dias por padrão.
- Pertencem à organização, não à pessoa. O saldo gasto é o da organização.
- Criar e revogar pede o papel de administrador ou dono.

## Escopos

| Escopo | Libera |
| --- | --- |
| `read` | Os métodos `GET`: modelos, saldo, gerações e arquivos. |
| `write` | `POST /v1/generations`, que gasta saldo. |
| `admin` | Ações administrativas pelo [MCP](https://hypio.doti.gg/docs/mcp). |

Um escopo não inclui outro. Uma chave só com `write` cria gerações, mas não consulta o resultado.

## Erros

| Status | `code` | Quando |
| --- | --- | --- |
| 401 | `unauthorized` | Chave ausente, inválida, revogada ou expirada. Vem com `WWW-Authenticate: Bearer`. |
| 403 | `insufficient_scope` | A chave não tem o escopo da rota. O corpo traz `requiredScope`. |
| 403 | `account_suspended` | A organização está suspensa. |