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

# Autenticação

> Como autenticar suas requisições na API do Synax

# Autenticação

A API do Synax usa **API Keys** para autenticação. Cada chave é vinculada a uma empresa e controla quais operações são permitidas.

## Obtendo sua API Key

1. Acesse o app em [app.synax.app.br](https://app.synax.app.br)
2. Vá em **Configurações** > **API**
3. Clique em **Nova chave**
4. Defina um nome e as permissões (leitura e/ou escrita)
5. Copie a chave gerada — ela só será mostrada uma vez

As chaves seguem o formato `sk_live_...`.

## Usando a API Key

Envie a chave no header `Authorization`:

```bash theme={null}
curl "https://api.synax.app.br/functions/v1/api-proxy/contacts?limit=10" \
  -H "Authorization: Bearer sk_live_SuaChaveAqui"
```

Ou no header `X-Api-Key`:

```bash theme={null}
curl "https://api.synax.app.br/functions/v1/api-proxy/contacts?limit=10" \
  -H "X-Api-Key: sk_live_SuaChaveAqui"
```

## Base URL

Todas as requisições devem ser feitas para:

```
https://api.synax.app.br/functions/v1/api-proxy
```

## Permissões (scopes)

| Scope   | Operações                  | Métodos HTTP        |
| ------- | -------------------------- | ------------------- |
| `read`  | Listar e consultar dados   | GET                 |
| `write` | Criar, atualizar e excluir | POST, PATCH, DELETE |

Ao criar uma chave, você escolhe quais permissões ela terá. Uma chave só de leitura não pode criar ou alterar dados.

## Segurança

* Cada chave é vinculada à sua empresa — só acessa dados da sua organização
* A chave é armazenada como hash no servidor — não é possível recuperá-la
* Você pode desativar ou excluir chaves a qualquer momento
* Chaves inativas são rejeitadas imediatamente

<Warning>
  Nunca exponha sua API Key no frontend ou em repositórios públicos. Use-a apenas em backends seguros.
</Warning>

## Erros de autenticação

| Status | Erro                                          | Causa                                          |
| ------ | --------------------------------------------- | ---------------------------------------------- |
| 401    | `Missing API key`                             | Header Authorization ou X-Api-Key ausente      |
| 401    | `Invalid or expired API key`                  | Chave incorreta, inativa ou expirada           |
| 403    | `This API key does not have write permission` | Tentativa de escrita com chave somente leitura |

## Exemplo completo

```bash theme={null}
# Criar um contato
curl -X POST "https://api.synax.app.br/functions/v1/api-proxy/contacts" \
  -H "Authorization: Bearer sk_live_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "phone": "+5511999999999",
    "email": "joao@email.com",
    "temperature": "warm",
    "source": "api"
  }'
```

**Resposta (201):**

```json theme={null}
{
  "data": {
    "id": "uuid-do-contato",
    "name": "João Silva",
    "phone": "+5511999999999",
    "email": "joao@email.com",
    "temperature": "warm",
    "source": "api",
    "created_at": "2026-02-27T12:00:00Z"
  }
}
```