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

# Autenticação

> Como autenticar requisições na API do Triglit usando chaves de API

A API pública do Triglit usa **chaves de API** para autenticação. O tenant é automaticamente identificado a partir da chave utilizada.

## Tipos de Chaves

O Triglit oferece dois tipos de chaves de API:

### Chave Pública (pk\_)

**Uso:** Frontend e aplicações client-side

* ✅ Pode ser exposta no frontend
* ✅ Escopos restritos (principalmente leitura)
* ✅ Rate limit mais agressivo
* ✅ Prefixo: `pk_`

### Chave Secreta (sk\_)

**Uso:** Backend e servidores

* ⚠️ **NUNCA** exponha no frontend ou repositórios públicos
* ✅ Escopos completos (criação, edição, exclusão)
* ✅ Rate limit apropriado para automações
* ✅ Prefixo: `sk_`

<Warning>
  Mantenha sua chave secreta em segurança. Se ela for comprometida, rotacione imediatamente no dashboard.
</Warning>

## Como Usar

### No Header da Requisição

Todas as requisições devem incluir a chave de API no header `X-API-Key`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.triglit.com/v1/gateway/workflows" \
    -H "X-API-Key: pk_sua_chave_aqui"
  ```

  ```javascript JavaScript theme={null}
  import Triglit from 'triglit';

  const client = new Triglit({ apiKey: 'pk_sua_chave_aqui' });
  const workflows = await client.workflows.list();
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'X-API-Key': 'pk_sua_chave_aqui'
  }

  response = requests.get(
      'https://api.triglit.com/v1/gateway/workflows',
      headers=headers
  )
  ```
</CodeGroup>

### Identificação do Tenant

O tenant é **automaticamente identificado** a partir da chave de API. Você não precisa enviar nenhum header adicional para identificar o tenant.

```json theme={null}
// A chave pk_abc123... pertence automaticamente ao tenant correto
// Não é necessário enviar X-Tenant-Id
```

## Escopos e Permissões

### Chave Pública (pk\_)

Endpoints permitidos:

* ✅ `GET /workflows` - Listar workflows
* ✅ `GET /workflows/{id}` - Obter workflow
* ✅ `GET /triggers` - Listar triggers
* ✅ `GET /workflow-versions` - Listar versões
* ✅ `POST /triggers` - Criar triggers (limitado)
* ❌ Operações de escrita em workflows
* ❌ Exclusão de recursos

### Chave Secreta (sk\_)

Endpoints permitidos:

* ✅ Todos os endpoints da chave pública
* ✅ `POST /workflows` - Criar workflows
* ✅ `PATCH /workflows/{id}` - Atualizar workflows
* ✅ `DELETE /workflows/{id}` - Excluir workflows
* ✅ `POST /workflow-versions` - Criar versões
* ✅ `POST /workflow-versions/{id}/publish` - Publicar versões
* ✅ Todas as operações de gestão

## Rate Limiting

### Chave Pública

* **Limite:** 100 requisições por minuto por tenant
* **Burst:** Até 20 requisições simultâneas

### Chave Secreta

* **Limite:** 1000 requisições por minuto por tenant
* **Burst:** Até 100 requisições simultâneas

### Headers de Rate Limit

A API retorna informações sobre rate limiting nos headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

### Resposta de Rate Limit Excedido

Quando o limite é excedido, você receberá:

```json theme={null}
{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in 5 seconds.",
  "error": "Too Many Requests"
}
```

## Erros de Autenticação

### 401 Unauthorized

A chave de API não foi fornecida ou é inválida:

```json theme={null}
{
  "statusCode": 401,
  "message": "API key não fornecida. Forneça a chave no header 'X-API-Key'.",
  "error": "Unauthorized"
}
```

**Soluções:**

* Verifique se o header `X-API-Key` está presente
* Confirme que a chave está correta
* Verifique se a chave não foi revogada

### 403 Forbidden

O tipo de chave não é permitido para este endpoint:

```json theme={null}
{
  "statusCode": 403,
  "message": "Tipo de chave não permitido. Este endpoint aceita apenas: secret key (sk_).",
  "error": "Forbidden"
}
```

**Soluções:**

* Use a chave secreta (sk\_) para operações de escrita
* Verifique a documentação do endpoint para ver quais tipos são aceitos

## Rotação de Chaves

### Quando Rotacionar

* Chave comprometida ou exposta
* Funcionário que tinha acesso saiu da empresa
* Rotação periódica de segurança (recomendado a cada 90 dias)

### Como Rotacionar

1. Acesse o Dashboard do Triglit
2. Vá em **Configurações** → **API Keys**
3. Clique em **Rotacionar Chaves**
4. Copie as novas chaves
5. Atualize suas aplicações
6. Revogue as chaves antigas após confirmar que tudo funciona

<Warning>
  Após rotacionar, as chaves antigas são imediatamente inválidas. Certifique-se de atualizar todas as aplicações antes de rotacionar.
</Warning>

## Boas Práticas

<AccordionGroup>
  <Accordion title="Armazenamento Seguro">
    * Nunca commite chaves em repositórios Git
    * Use variáveis de ambiente
    * Use serviços de gerenciamento de secrets (AWS Secrets Manager, HashiCorp Vault, etc.)
    * Rotacione chaves regularmente
  </Accordion>

  <Accordion title="Uso Correto das Chaves">
    * Use chave pública (pk\_) apenas no frontend
    * Use chave secreta (sk\_) apenas no backend
    * Não compartilhe chaves entre ambientes (dev/prod)
    * Monitore o uso das chaves
  </Accordion>

  <Accordion title="Tratamento de Erros">
    * Sempre trate erros 401 e 403
    * Implemente retry com backoff exponencial
    * Monitore rate limits
    * Logue erros de autenticação para debugging
  </Accordion>
</AccordionGroup>

## Exemplo Completo

<CodeGroup>
  ```javascript JavaScript theme={null}
  import Triglit from 'triglit';

  // Inicializar o cliente com sua chave de API
  const client = new Triglit({ apiKey: 'sk_sua_chave_secreta' });

  // Listar workflows
  const workflows = await client.workflows.list();

  // Obter um workflow específico
  const workflow = await client.workflows.retrieve('workflow_id_aqui');

  // Criar uma versão de workflow
  const version = await client.workflows.versions.create({
    workflowId: 'workflow_id_aqui',
    nodes: [],
    edges: []
  });

  // Listar triggers
  const triggers = await client.triggers.list();
  ```

  ```python Python theme={null}
  import requests
  from typing import Optional, Dict, Any

  class TriglitClient:
      def __init__(self, api_key: str):
          self.api_key = api_key
          self.base_url = 'https://api.triglit.com/v1/gateway'
          self.headers = {
              'X-API-Key': api_key,
              'Content-Type': 'application/json'
          }

      def _request(self, method: str, endpoint: str, data: Optional[Dict] = None) -> Dict[str, Any]:
          url = f'{self.base_url}{endpoint}'
          response = requests.request(
              method=method,
              url=url,
              headers=self.headers,
              json=data
          )
          response.raise_for_status()
          return response.json()

      def get_workflows(self):
          return self._request('GET', '/workflows')

      def create_workflow(self, data: Dict[str, Any]):
          return self._request('POST', '/workflows', data)

  # Uso
  client = TriglitClient('sk_sua_chave_secreta')
  workflows = client.get_workflows()
  ```
</CodeGroup>

<Tip>
  Use o SDK oficial do Triglit para facilitar o gerenciamento de autenticação, tratamento de erros e rate limiting. Instale com `npm install triglit`.
</Tip>