> 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/construir/api-http/autenticacao-e-headers.md).

# Autenticação e headers

Toda chamada à API HTTP do skail leva dois headers: a chave do environment e 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`.

As duas rotas públicas são:

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

## Headers obrigatórios

| Header            | Valor                                                     | Observação                                                                             |
| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `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.                                                          |

O nome dos headers não diferencia maiúsculas de minúsculas em HTTP; a doc usa `skail-key` e `Skail-namespace` por convenção. Esses dois headers são a autenticação da API.

## 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                                                                           |
| ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `401`       | Header ausente, chave inválida ou desabilitada             | Confira `skail-key` e se a chave 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` | Corpo ou caminho inválido                                  | Confira o JSON do corpo (array no trigger, objeto no fire) e os segmentos do caminho. |
| `5xx`       | Falha no skail                                             | Retente com backoff.                                                                  |

## Exemplo mínimo

```bash
curl -X POST "https://SEU_SKAIL_BASE_URL/trigger/faturamento/v1.0.0/EmitirFatura/8f2c3a10-0000-4000-8000-000000000001" \
  -H "Content-Type: application/json" \
  -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 `IHttpClientFactory` (ou equivalente) com os headers pré-configurados, como nos exemplos de [Como disparar uma função pela API HTTP](/construir/escrever-fluxos/como-disparar-uma-funcao-pela-api-http.md). Trate `429` e `5xx` com retry e backoff no chamador: o trigger é a única etapa do fluxo que ainda não está sob a durabilidade do skail.

## Veja também

[POST /trigger](/construir/api-http/post-trigger-workload-versao-funcao-id.md), [POST /api/v1/fire](/construir/api-http/post-api-v1-fire-eventname-instanceid.md), [Chaves: criar, rotacionar, revogar](/operar/chaves-criar-rotacionar-revogar.md).