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

# Authentication

# Autenticação

> Como autenticar suas requisições com API Keys do ConnectVets Notes

# Autenticação com API Keys 🔐

O ConnectVets Notes usa **API Keys** para autenticar todas as requisições. É simples, seguro e permite controle granular de acesso.

<Info>
  **Todas as requisições** para a API ConnectVets Notes devem incluir uma API Key válida no header `X-API-KEY`.
</Info>

## Como funciona

<Steps>
  <Step title="Obtenha uma API Key">
    Crie uma API Key no dashboard do ConnectVets Notes
  </Step>

  <Step title="Inclua no header">
    Adicione o header `X-API-KEY` em todas as requisições
  </Step>

  <Step title="Faça a requisição">
    Envie sua requisição - a autenticação é automática
  </Step>
</Steps>

## Criando uma API Key

### Pelo Dashboard Web

<Steps>
  <Step title="Acesse o Dashboard">
    Faça login em [notes.connectvets.com.br](https://notes.connectvets.com.br)
  </Step>

  <Step title="Navegue para API Keys">
    Vá para **Configurações** → **API Keys** no menu lateral
  </Step>

  <Step title="Crie uma nova chave">
    Clique em **"Nova API Key"** e preencha:

    * **Nome**: Identifique o uso (ex: "Integração Sistema X")
    * **Tipo**: Selecione as permissões necessárias
    * **Expiração**: Defina quando expira (opcional)
  </Step>

  <Step title="Copie a chave">
    ⚠️ **Importante**: Copie a chave imediatamente - ela só aparece uma vez!
  </Step>
</Steps>

### Via API (para automação)

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X POST "https://api-sandbox.connectvets.com.br/notes/v1/api-keys" \
    -H "X-API-KEY: your_admin_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Integração Sistema X",
      "permissions": ["notes:read", "notes:write"],
      "expires_at": "2024-12-31T23:59:59Z"
    }'
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch('https://api-sandbox.connectvets.com.br/notes/v1/api-keys', {
    method: 'POST',
    headers: {
      'X-API-KEY': 'your_admin_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Integração Sistema X',
      permissions: ['notes:read', 'notes:write'],
      expires_at: '2024-12-31T23:59:59Z'
    })
  });

  const apiKey = await response.json();
  console.log('Nova API Key:', apiKey.data.key);
  ```

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

  data = {
      'name': 'Integração Sistema X',
      'permissions': ['notes:read', 'notes:write'],
      'expires_at': '2024-12-31T23:59:59Z'
  }

  response = requests.post(
      'https://api-sandbox.connectvets.com.br/notes/v1/api-keys',
      headers={'X-API-KEY': 'your_admin_key'},
      json=data
  )

  api_key = response.json()
  print(f"Nova API Key: {api_key['data']['key']}")
  ```
</CodeGroup>

## Usando API Keys

Inclua sua API Key no header `X-API-KEY` de todas as requisições:

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api-sandbox.connectvets.com.br/notes/v1/notes" \
    -H "X-API-KEY: cvn_1234567890abcdef" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null} theme={null}
  // Fetch API
  const response = await fetch('https://api-sandbox.connectvets.com.br/notes/v1/notes', {
    headers: {
      'X-API-KEY': 'cvn_1234567890abcdef',
      'Content-Type': 'application/json'
    }
  });

  // Axios
  import axios from 'axios';

  const api = axios.create({
    baseURL: 'https://api-sandbox.connectvets.com.br/notes/v1',
    headers: {
      'X-API-KEY': 'cvn_1234567890abcdef'
    }
  });
  ```

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

  # Session com header padrão
  session = requests.Session()
  session.headers.update({
      'X-API-KEY': 'cvn_1234567890abcdef',
      'Content-Type': 'application/json'
  })

  response = session.get('https://api-sandbox.connectvets.com.br/notes/v1/notes')
  ```

  ```go Go theme={null} theme={null}
  package main

  import (
      "net/http"
  )

  func main() {
      client := &http.Client{}
      req, _ := http.NewRequest("GET", "https://api-sandbox.connectvets.com.br/notes/v1/notes", nil)
      
      req.Header.Add("X-API-KEY", "cvn_1234567890abcdef")
      req.Header.Add("Content-Type", "application/json")
      
      resp, _ := client.Do(req)
      defer resp.Body.Close()
  }
  ```
</CodeGroup>

## Tipos de API Keys

<CardGroup cols={3}>
  <Card title="Administrador" icon="crown" color="#f59e0b">
    **Permissões**: Todas

    * Criar/deletar API Keys
    * Gerenciar usuários
    * Acesso completo às notas
  </Card>

  <Card title="Editor" icon="pencil" color="#3b82f6">
    **Permissões**: Leitura e escrita

    * Criar notas
    * Atualizar notas existentes
    * Visualizar todas as notas
  </Card>

  <Card title="Visualizador" icon="eye" color="#10b981">
    **Permissões**: Somente leitura

    * Visualizar notas
    * Buscar e filtrar
    * Sem permissões de escrita
  </Card>
</CardGroup>

## Anatomia de uma API Key

As API Keys do ConnectVets seguem um formato específico para facilitar identificação:

<Frame>
  ```
  cvn_1234567890abcdef1234567890abcdef
  │   │                                
  │   └── Chave secreta (32 caracteres hex)
  └── Prefixo identificador ConnectVets Notes
  ```
</Frame>

<Accordion title="Detalhes técnicos">
  * **Prefixo**: `cvn_` identifica chaves do ConnectVets Notes
  * **Comprimento**: 36 caracteres total (4 do prefixo + 32 da chave)
  * **Formato**: Hexadecimal (0-9, a-f)
  * **Geração**: Cryptographically secure random
  * **Encoding**: UTF-8
</Accordion>

## Segurança e Boas Práticas

<CardGroup cols={2}>
  <Card title="✅ Faça" icon="check" color="#10b981">
    * Armazene em variáveis de ambiente
    * Use HTTPS em produção
    * Monitore uso das chaves
    * Rotacione chaves regularmente
    * Use chaves com permissões mínimas
  </Card>

  <Card title="❌ Não faça" icon="x" color="#ef4444">
    * Commitar chaves no código
    * Logar chaves em arquivos
    * Compartilhar chaves por email/chat
    * Usar chaves de admin para tudo
    * Deixar chaves sem expiração
  </Card>
</CardGroup>

### Armazenamento Seguro

<CodeGroup>
  ```bash Variáveis de Ambiente theme={null} theme={null}
  # .env
  CONNECTVETS_API_KEY=cvn_1234567890abcdef

  # .bashrc ou .zshrc
  export CONNECTVETS_API_KEY=cvn_1234567890abcdef
  ```

  ```javascript Node.js theme={null} theme={null}
  // Usando dotenv
  require('dotenv').config();

  const apiKey = process.env.CONNECTVETS_API_KEY;

  // Ou usando config
  const config = {
    apiKey: process.env.CONNECTVETS_API_KEY || 'fallback_for_dev'
  };
  ```

  ```python Python theme={null} theme={null}
  import os
  from dotenv import load_dotenv

  load_dotenv()

  API_KEY = os.getenv('CONNECTVETS_API_KEY')

  # Ou usando python-decouple
  from decouple import config
  API_KEY = config('CONNECTVETS_API_KEY')
  ```

  ```go Go theme={null} theme={null}
  package main

  import (
      "os"
      "log"
  )

  func main() {
      apiKey := os.Getenv("CONNECTVETS_API_KEY")
      if apiKey == "" {
          log.Fatal("CONNECTVETS_API_KEY não encontrada")
      }
  }
  ```
</CodeGroup>

## Rate Limiting

API Keys têm limites de taxa baseados no tipo:

<CardGroup cols={3}>
  <Card title="Administrador" icon="crown" color="#f59e0b">
    **1000 req/min**
    Limite mais alto para operações administrativas
  </Card>

  <Card title="Editor" icon="pencil" color="#3b82f6">
    **500 req/min**
    Limite moderado para operações normais
  </Card>

  <Card title="Visualizador" icon="eye" color="#10b981">
    **200 req/min**
    Limite conservador para consultas
  </Card>
</CardGroup>

### Respondendo ao Rate Limiting

Quando você excede o limite, a API retorna `429 Too Many Requests`:

<CodeGroup>
  ```json Resposta 429 theme={null} theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded. Try again in 60 seconds.",
      "details": {
        "limit": 500,
        "remaining": 0,
        "reset_at": "2024-01-15T10:31:00Z"
      }
    }
  }
  ```

  ```javascript Tratamento em JS theme={null} theme={null}
  async function apiCall() {
    try {
      const response = await fetch(url, { headers });
      
      if (response.status === 429) {
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = new Date(resetTime) - new Date();
        
        console.log(`Rate limit hit. Waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        
        return apiCall(); // Retry
      }
      
      return response.json();
    } catch (error) {
      console.error('API Error:', error);
    }
  }
  ```

  ```python Tratamento em Python theme={null} theme={null}
  import time
  import requests

  def api_call_with_retry():
      while True:
          response = requests.get(url, headers=headers)
          
          if response.status_code == 429:
              reset_time = response.headers.get('X-RateLimit-Reset')
              wait_time = int(reset_time) - int(time.time())
              
              print(f"Rate limit hit. Waiting {wait_time}s...")
              time.sleep(wait_time)
              continue
              
          return response.json()
  ```
</CodeGroup>

## Monitoramento e Logs

### Verificar uso de uma API Key

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api-sandbox.connectvets.com.br/notes/v1/api-keys/cvn_1234567890abcdef/usage" \
    -H "X-API-KEY: your_admin_key"
  ```

  ```javascript JavaScript theme={null} theme={null}
  const usage = await fetch(`https://api-sandbox.connectvets.com.br/notes/v1/api-keys/${keyId}/usage`, {
    headers: { 'X-API-KEY': 'your_admin_key' }
  });

  const stats = await usage.json();
  console.log('Uso da API Key:', stats.data);
  ```
</CodeGroup>

### Listar todas as API Keys

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api-sandbox.connectvets.com.br/notes/v1/api-keys" \
    -H "X-API-KEY: your_admin_key"
  ```

  ```javascript JavaScript theme={null} theme={null}
  const keys = await fetch('https://api-sandbox.connectvets.com.br/notes/v1/api-keys', {
    headers: { 'X-API-KEY': 'your_admin_key' }
  });

  const apiKeys = await keys.json();
  console.log('API Keys ativas:', apiKeys.data);
  ```
</CodeGroup>

## Rotação de Chaves

Para manter a segurança, rotacione suas API Keys regularmente:

<Steps>
  <Step title="Crie uma nova API Key">
    Gere uma nova chave com as mesmas permissões
  </Step>

  <Step title="Atualize seus sistemas">
    Substitua a chave antiga pela nova em todos os sistemas
  </Step>

  <Step title="Teste a integração">
    Verifique se tudo funciona com a nova chave
  </Step>

  <Step title="Revogue a chave antiga">
    Delete a chave antiga do dashboard
  </Step>
</Steps>

<Warning>
  **Cuidado**: Sempre teste a nova chave antes de revogar a antiga para evitar interrupções no serviço.
</Warning>

## Resolução de Problemas

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **Possíveis causas:**

    * API Key inválida ou expirada
    * Header `X-API-KEY` ausente
    * Typo na chave

    **Soluções:**

    * Verifique se a chave está correta
    * Confirme que o header está sendo enviado
    * Regenere a chave se necessário
  </Accordion>

  <Accordion title="403 Forbidden">
    **Possíveis causas:**

    * API Key sem permissões suficientes
    * Tentativa de acessar recursos de outro tenant
    * Chave desabilitada

    **Soluções:**

    * Use uma chave com permissões adequadas
    * Verifique se está acessando o tenant correto
    * Confirme se a chave está ativa
  </Accordion>

  <Accordion title="429 Too Many Requests">
    **Possíveis causas:**

    * Limite de rate excedido
    * Muitas requisições simultâneas

    **Soluções:**

    * Implemente retry com backoff
    * Distribua requisições ao longo do tempo
    * Use cache para reduzir chamadas
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Fazer primeira requisição" icon="play" href="/notes/quickstart">
    Use sua API Key para processar o primeiro áudio
  </Card>

  <Card title="Explorar endpoints" icon="code" href="/notes/api-reference/overview">
    Veja todos os endpoints disponíveis
  </Card>

  <Card title="Configurar webhooks" icon="webhook" href="/notes/concepts/webhooks">
    Receba notificações automáticas de eventos
  </Card>

  <Card title="Exemplos de integração" icon="puzzle-piece" href="/notes/examples/basic-integration">
    Veja implementações práticas
  </Card>
</CardGroup>