Ir para o conteúdo

Autenticação

🤖 Explicar com IA

Para garantir a integridade e a segurança de todas as trocas de dados, a 4Geeks implementa a Autenticação via Chave de API como o padrão arquitetural principal para autorizar solicitações de serviço recebidas. Sob este protocolo, cada interação programática deve ser acompanhada por uma Chave de API única e válida; a falha em fornecer esta credencial resultará em uma negação imediata de autorização para proteger os recursos sensíveis do sistema. Essas credenciais são enviadas utilizando a estrutura HTTP Basic Authentication, conforme estritamente definido pelo padrão industrial RFC 7617, que requer que a chave seja passada no cabeçalho da solicitação de acordo com as convenções de formatação específicas detalhadas na seguinte documentação técnica.

Authorization: Basic <base64_encoded_credentials>

Onde <base64_encoded_credentials> é a sua Chave de API seguida por dois pontos (:) e então codificada em Base64.

Codificação Passo a Passo

1. Sua Chave de API:

sk_test_51O62xYzAbcDef123

2. Adicione dois pontos após a chave: 

sk_test_51O62xYzAbcDef123:

3. Codifique para Base64: 

c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

4. Adicione ao cabeçalho Authorization: 

Authorization: Basic c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

Exemplos de Código

curl -X GET 'http://api.4geeks.io/v1/customers/' \
  -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.get(
    'http://api.4geeks.io/v1/customers/',
    headers={
        'Authorization': f'Api-Key {api_key}'
    }
)
print(response.json())

const apiKey = "sk_test_51O62xYzAbcDef123";

fetch("http://api.4geeks.io/v1/customers/", {
    method: "GET",
    headers: {
        Authorization: `Api-Key ${apiKey}`,
    },
})
    .then((res) => res.json())
    .then((data) => console.log(data));

import { HttpClient, HttpHeaders } from "@angular/common/http";

export class CustomerService {
    private apiKey = "sk_test_51O62xYzAbcDef123";

    constructor(private http: HttpClient) {}

    getCustomers() {
        const headers = new HttpHeaders({
            Authorization: `Api-Key ${this.apiKey}`,
        });

        return this.http.get("http://api.4geeks.io/v1/customers/", { headers });
    }
}

Tratamento de Erros

400 Bad Request (Solicitação Inválida)

Ocorre quando a solicitação não contém os campos obrigatórios ou possui um formato inválido.

Exemplo:

{
    "message": {
        "code": 400,
        "title": "Invalid request",
        "content": "Please provide a valid 'type' field: 'test' or 'live'.",
        "type": "danger"
    }
}

Causas:

  • Falta do campo type em uma solicitação PATCH
  • Valor de type inválido (deve ser "test" ou "live")

Solução: Inclua {"type": "test"} ou {"type": "live"} no corpo da solicitação.

401 Unauthorized (Não Autorizado)

Falha na autenticação. A Chave de API é inválida, está ausente ou malformada.

Exemplos:

  1. Ausência do Cabeçalho de Autorização (Bearer Token)
Solicitação: GET /v1/auth/api-keys/ (sem cabeçalho Authorization)
Resposta:
{
  "detail": "Authentication credentials were not provided."
}
  1. Chave não Encontrada
Solicitação: Cabeçalho Authorization com uma chave inexistente
Resposta:
{
    "detail": "Given token not valid for any token type",
    "code": "token_not_valid",
    "messages": [
        {
            "token_class": "AccessToken",
            "token_type": "access",
            "message": "Token is invalid or expired"
        }
    ]
}

Soluções:

  • Verifique se você incluiu o cabeçalho Authorization: Bearer <Bearer_Token>
  • Verifique se a chave não foi rotacionada recentemente
  • Teste com o Postman para depurar o problema

404 Not Found (Não Encontrado)

Não existem Chaves de API para este usuário.

Exemplo:

{
    "code": 404,
    "title": "API Keys not found",
    "content": "No API keys found for this user. Please contact support.",
    "type": "warning"
}

Solução: Entre em contato com o suporte para inicializar as chaves de API para sua conta.

Melhores Práticas de Segurança

Mantenha Suas Chaves Seguras

  • Armazene as chaves em variáveis de ambiente, nunca no código.
  • Não envie chaves para sistemas de controle de versão (como Git).
  • Use arquivos .env com um arquivo .gitignore.
  • Rotacione as chaves a cada 3 a 6 meses.
  • Gere novas chaves imediatamente caso sejam expostas.

Exemplo de Variável de Ambiente:

# .env
API_KEY_TEST=sk_test_51O62xYzAbcDef123
API_KEY_LIVE=sk_live_xYzAbcDef123456789
API_URL=http://api.4geeks.io

Uso na Aplicação:

import os
api_key = os.getenv('API_KEY_TEST')

Solução de Problemas

Problema: 401 Unauthorized “Invalid API Key format”

Causas:

  • A Chave de API está incompleta ou truncada.
  • A codificação Base64 não inclui os dois pontos (:).
  • Espaços extras na chave ou no cabeçalho.
  • A chave foi regenerada recentemente.

Soluções:

  1. Copie a chave novamente:
    • Vá para as Configurações do dashboard → Chaves de API.
    • Copie a chave completa cuidadosamente.

  2. Verifique a codificação Base64:

  3. Teste com o Postman:

    • Crie uma nova solicitação.
    • Authorization → Basic Auth.
    • Username: [sua chave completa].
    • Password: [deixe em branco].
    • Envie.

Problema: A chave parou de funcionar após a rotação

Causa: Você rotacionou a chave, mas sua aplicação ainda está usando a antiga.

Solução:

  1. Vá para Configurações → Chaves de API.
  2. Copie a nova chave.
  3. Atualize seu arquivo .env ou configuração.
  4. Reinicie sua aplicação.

Problema: 404 “API Keys not found”

Causa: Nenhuma chave de API foi inicializada para sua conta.

Solução: Entre em contato com o suporte para inicializar suas chaves de API.

Perguntas Frequentes (FAQ)

P: Posso ter múltiplas Chaves de API? R: Não. Você possui exatamente uma Chave de Teste e uma Chave de Produção (Live). Use o endpoint de rotação para regenerá-las.

P: O que acontece se eu expuser minha Chave de Produção? R: Rotacione-a imediatamente pelo dashboard. A chave exposta se tornará inválida em 1 minuto.

P: Posso usar a mesma chave para Teste e Produção? R: Não. As chaves de Teste e Produção são separadas. Use sempre as Chaves de Teste durante o desenvolvimento.

P: Preciso atualizar minha Chave de API? R: Diferente dos tokens JWT, as Chaves de API não expiram. Elas permanecem válidas até que você as rotacione.

P: Posso usar Chaves de API com webhooks? R: Não. Os webhooks são entregues por nossos servidores ao seu endpoint. Você autentica o webhook usando assinaturas, não Chaves de API.