> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/referencia/api-http/autenticacao.md).

# Autenticação

Toda chamada à API HTTP do skail leva três headers: `Authorization` e `skail-key`, os dois com a chave do environment, e `Skail-namespace`, com o namespace. Esta página é a referência deles e da URL base.

## URL base

Cada environment tem uma URL base para a API HTTP; ela está na tela do environment no portal, junto com a chave e o namespace. Nos exemplos desta documentação ela aparece como `https://SEU_SKAIL_BASE_URL`. A URL base é o endereço do environment, sem `/api/v1` no final; as duas rotas começam com `/api/v1`.

As duas rotas públicas são:

| Rota                                                     | Para que serve                                                                                                           |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `POST /api/v1/trigger/{workload}/{versao}/{funcao}/{id}` | Iniciar a execução de uma function. Referência: [POST /api/v1/trigger](/referencia/api-http/post-trigger.md).            |
| `POST /api/v1/fire/{eventName}/{instanceId}`             | Disparar um evento que libera uma espera por evento. Referência: [POST /api/v1/fire](/referencia/api-http/post-fire.md). |

## Headers obrigatórios

| Header            | Valor                                                     | Observação                                                                             |
| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `Authorization`   | `Bearer <chave do environment>`                           | A mesma chave de `skail-key`, com o prefixo `Bearer`.                                  |
| `skail-key`       | Chave do environment                                      | A mesma de `SKAIL_KEY` do runtime. Segredo: nunca em código versionado nem em URL.     |
| `Skail-namespace` | Namespace do environment, no formato `tenant/environment` | O mesmo de `SKAIL_NAMESPACE`. O skail confere que a chave pertence a esse environment. |
| `Content-Type`    | `application/json`                                        | Corpo em JSON nas duas rotas.                                                          |

{% hint style="info" %}
O nome dos headers não diferencia maiúsculas de minúsculas em HTTP; a doc usa `Authorization`, `skail-key` e `Skail-namespace` por convenção. Esses três headers são a autenticação da API.
{% endhint %}

## Como a autorização é avaliada

A chave precisa existir, estar habilitada e pertencer ao environment indicado no namespace. Uma chave de `dev` usada com o namespace de `prod` é recusada. Revogar ou desabilitar uma chave leva até um minuto para valer em todas as chamadas.

## Respostas de erro

| Status      | Significado                                                                                                                                 | O que fazer                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `400`       | Header ausente: `{"error":"missing_headers","message":"Authorization header is required."}`                                                 | Confira se a chamada leva `Authorization`, `skail-key` e `Skail-namespace`.                  |
| `400`       | Id do trigger que não é GUID, ou corpo inválido: `{"error":"invalid_body","message":"Request body field \"taskId\" must be a valid GUID."}` | Use um GUID no `id` do trigger e confira o JSON do corpo (array no trigger, objeto no fire). |
| `401`       | Chave inválida ou desabilitada                                                                                                              | Confira a chave em `Authorization` e `skail-key` e se ela está ativa no portal.              |
| `403`       | Chave válida, mas não pertence ao environment do namespace                                                                                  | Confira `Skail-namespace`; o segundo componente precisa ser o environment da chave.          |
| outro `4xx` | Caminho inválido                                                                                                                            | Confira os segmentos do caminho.                                                             |
| `5xx`       | Falha no skail                                                                                                                              | Retente com backoff.                                                                         |

## Exemplo mínimo

```bash
curl -X POST "https://SEU_SKAIL_BASE_URL/api/v1/trigger/faturamento/v1.0.0/EmitirFatura/SEU_GUID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SUA_SKAIL_KEY" \
  -H "skail-key: SUA_SKAIL_KEY" \
  -H "Skail-namespace: SEU_NAMESPACE" \
  -d '["8f2c3a10-0000-4000-8000-000000000001"]'
```

## Boas práticas

Guarde chave, namespace e URL base na configuração do sistema que chama o skail, uma por environment. Use um cliente HTTP com os headers pré-configurados, como nos exemplos de [Como disparar uma função pela API HTTP](/construa/como-fazer/disparar-uma-funcao-pela-api.md). Trate `429` e `5xx` com retry e backoff no chamador: o trigger e o fire ficam fora da durabilidade do skail.

## Veja também

[POST /api/v1/trigger](/referencia/api-http/post-trigger.md), [POST /api/v1/fire](/referencia/api-http/post-fire.md), [Chaves: criar, rotacionar, revogar](/opere/configurar-e-hospedar/chaves.md).