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

# Autenticação

> Aprenda como autenticar com a API Talkover usando tokens de ambiente

# Autenticação

A API Talkover usa autenticação Bearer token com tokens de ambiente. Todas as requisições da API devem incluir um token de ambiente válido no cabeçalho Authorization.

## Visão Geral

A autenticação é gerenciada através de **Tokens de Ambiente** que você pode gerar no seu painel Talkover. Esses tokens fornecem acesso seguro aos recursos da sua conta e são usados para autenticar todas as requisições da API.

## Obtendo Seu Token de Ambiente

### Passo 1: Acessar Seu Painel

1. **Faça login** na sua conta Talkover em [app.talkover.ai](https://app.talkover.ai)
2. **Navegue para Conta** na barra lateral esquerda
3. **Clique em "Ambientes"**

### Passo 2: Encontrar Seu Token

Seus tokens de ambiente serão exibidos na seção Ambientes. Cada ambiente tem seu próprio token que começa com `talq_` seguido por uma longa string de caracteres.

<Note>
  Tokens de ambiente são credenciais sensíveis. Mantenha-os seguros e nunca os compartilhe publicamente ou os cometa no controle de versão.
</Note>

## Usando Seu Token de Ambiente

### Cabeçalho de Autorização

Inclua seu token de ambiente no cabeçalho `Authorization` de todas as requisições da API:

```bash theme={null}
Authorization: Bearer talq_seu_token_de_ambiente_aqui
```

### Exemplo de Requisição

```bash theme={null}
curl -H "Authorization: Bearer talq_seu_token_de_ambiente_aqui" \
  https://app.talkover.ai/api/v1/health
```

## Melhores Práticas de Segurança

### 1. Manter Tokens Seguros

* **Nunca exponha tokens** em código do lado do cliente ou repositórios públicos
* **Use variáveis de ambiente** para armazenar tokens de forma segura
* **Rotacione tokens regularmente** para segurança aprimorada
* **Monitore o uso de tokens** para atividade suspeita

### 2. Gerenciamento de Tokens

* **Use tokens diferentes** para diferentes ambientes (desenvolvimento, homologação, produção)
* **Limite permissões de tokens** apenas ao que é necessário
* **Revogue tokens comprometidos** imediatamente
* **Use expiração de tokens** quando disponível

### 3. Segurança de Requisições

* **Sempre use HTTPS** para requisições da API
* **Valide respostas** para garantir que vêm da Talkover
* **Trate erros graciosamente** sem expor informações sensíveis
* **Registre requisições de forma segura** sem incluir tokens

## Variáveis de Ambiente

Armazene seu token de ambiente de forma segura usando variáveis de ambiente:

### Bash/Shell

```bash theme={null}
export TALKOVER_TOKEN="talq_seu_token_de_ambiente_aqui"
```

### JavaScript/Node.js

```javascript theme={null}
const token = process.env.TALKOVER_TOKEN;
```

### Python

```python theme={null}
import os
token = os.environ.get('TALKOVER_TOKEN')
```

### PHP

```php theme={null}
$token = getenv('TALKOVER_TOKEN');
```

## Exemplos de Código

### cURL

```bash theme={null}
curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer $TALKOVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321"
  }'
```

### JavaScript

```javascript theme={null}
const response = await fetch('https://app.talkover.ai/api/v1/agents/agent_123456/call', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TALKOVER_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+5511987654321'
  })
});
```

### Python

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

headers = {
    'Authorization': f'Bearer {os.environ.get("TALKOVER_TOKEN")}',
    'Content-Type': 'application/json'
}

data = {
    'to': '+5511987654321'
}

response = requests.post(
    'https://app.talkover.ai/api/v1/agents/agent_123456/call',
    headers=headers,
    json=data
)
```

### PHP

```php theme={null}
$token = getenv('TALKOVER_TOKEN');
$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
];

$data = [
    'to' => '+5511987654321'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.talkover.ai/api/v1/agents/agent_123456/call');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
```

## Respostas de erro

### Token Inválido

```json theme={null}
{
  "error": "UNAUTHORIZED",
  "message": "Token de autenticação inválido ou ausente",
  "status_code": 401
}
```

### Token Expirado

```json theme={null}
{
  "error": "TOKEN_EXPIRED",
  "message": "Token de autenticação expirou",
  "status_code": 401
}
```

### Token Ausente

```json theme={null}
{
  "error": "MISSING_TOKEN",
  "message": "Cabeçalho de autorização é obrigatório",
  "status_code": 401
}
```

## Escopos e Permissões de Tokens

Tokens de ambiente têm acesso a:

* **Agentes de Voz** - Criar, ler, atualizar e excluir agentes de voz
* **Chamadas** - Iniciar e gerenciar chamadas
* **Campanhas** - Criar e gerenciar campanhas de chamada
* **Histórico de Chamadas** - Acessar logs e análises de chamadas
* **Configurações da Conta** - Ler informações da conta

<Warning>
  Tokens de ambiente têm acesso total à sua conta. Use-os responsavelmente e nunca os compartilhe com partes não autorizadas.
</Warning>

## Solução de Problemas

### Problemas Comuns

1. **Erro "Token inválido"**
   * Verifique se o token está correto e completo
   * Verifique se o token começa com `talq_`
   * Certifique-se de que não há espaços ou caracteres extras

2. **Erro "Token expirado"**
   * Gere um novo token de ambiente
   * Atualize sua aplicação com o novo token
   * Verifique as configurações de expiração do token

3. **Erro "Token ausente"**
   * Certifique-se de que o cabeçalho Authorization está incluído
   * Verifique o formato do cabeçalho: `Bearer <token>`
   * Verifique se o token não está vazio

### Obtendo Ajuda

Se você está enfrentando problemas de autenticação:

1. **Verifique seu token** no painel
2. **Verifique o formato da requisição** corresponde aos exemplos
3. **Teste com uma requisição simples** como o endpoint de saúde
4. **Entre em contato com o suporte** se o problema persistir

## Próximos Passos

* **Faça sua primeira chamada** em nosso [Guia da Primeira Chamada](/pt-br/getting-started/first-call)
* **Aprenda sobre endpoints da API** em nossa [Referência da API](/pt-br/api-reference/endpoints/make-call)
* **Explore exemplos de integração** em nossos [Exemplos de Integração](/pt-br/guides/integration-examples)