Autenticação

Todas as requisições à API External do Efflux requerem autenticação usando uma API key. Este guia explica como a autenticação funciona e como gerenciar suas API keys.

Autenticação via API Key

Toda requisição deve incluir sua API key no header X-API-Key:

curl -X GET "https://api.efflux.media/api/external/content" \
  -H "X-API-Key: efflux_live_minhaempresa_abc123..."

Mantenha sua API key segura

• Nunca exponha API keys em código client-side ou repositórios públicos
• Use variáveis de ambiente para armazenar API keys
• Faça rotação das keys periodicamente e imediatamente se comprometidas

Formato da API Key

As API keys do Efflux seguem um formato estruturado:

efflux_live_{tenant_slug}_{43_caracteres_aleatorios}

Componente	Descrição
efflux_live_	Prefixo fixo identificando keys de produção do Efflux
{tenant_slug}	Identificador único da sua organização
{43_chars_aleatorios}	String aleatória criptograficamente segura

Exemplo: efflux_live_acmecorp_7Kj9mN2pL5qR8sT1vW3xY6zA0bC4dE

Escopos

API keys são configuradas com escopos específicos que determinam quais recursos podem acessar. Requisições a endpoints sem o escopo necessário retornarão erro 403 Forbidden.

Escopos Disponíveis

Escopo	Endpoints	Descrição
content:read	/content, /content/{id}	Acesso a itens de conteúdo e metadados
schedules:read	/schedules	Acesso a programações
players:read	/players	Acesso a informações de dispositivos player
analytics:read	/analytics/summary	Acesso a analytics e métricas

Verificando Escopos

Quando você cria uma API key, os escopos selecionados são permanentemente associados a ela. Para visualizar ou modificar escopos, você precisará criar uma nova key.

Dica

Siga o princípio do menor privilégio: solicite apenas os escopos que sua integração realmente precisa.

Criando API Keys

API keys são criadas no Backoffice Efflux:

1. Faça login em app.efflux.media
2. Navegue até Configurações > API Keys
3. Clique em Criar API Key
4. Configure:
   • Nome: Identificador descritivo (ex: “Integração Dashboard”)
   • Descrição: Notas opcionais sobre o propósito da key
   • Escopos: Selecione as permissões necessárias
   • Expiração: Data de expiração opcional

Importante

A API key completa é exibida apenas uma vez quando criada. Copie e armazene-a de forma segura imediatamente.

Ciclo de Vida da Key

Keys Ativas

Keys ativas podem ser usadas para autenticar requisições da API. Você pode visualizar keys ativas no Backoffice, mas apenas o prefixo é mostrado por segurança.

Keys Expiradas

Keys com data de expiração tornam-se inválidas após essa data. Requisições com keys expiradas retornam:

{
  "error": "API key has expired",
  "code": "KEY_EXPIRED"
}

Keys Revogadas

Keys podem ser revogadas a qualquer momento no Backoffice. Keys revogadas tornam-se imediatamente inválidas:

{
  "error": "API key has been revoked",
  "code": "KEY_REVOKED"
}

Boas Práticas de Segurança

Variáveis de Ambiente

Armazene API keys em variáveis de ambiente, nunca no código:

Node.js

.env

EFFLUX_API_KEY=efflux_live_minhaempresa_abc123...

// app.js
const apiKey = process.env.EFFLUX_API_KEY;

Python

.env

EFFLUX_API_KEY=efflux_live_minhaempresa_abc123...

# app.py
import os
api_key = os.environ.get('EFFLUX_API_KEY')

Bash

export EFFLUX_API_KEY="efflux_live_minhaempresa_abc123..."

curl -H "X-API-Key: $EFFLUX_API_KEY" \
  https://api.efflux.media/api/external/content

Rotação de Keys

Faça rotação regular das API keys para minimizar riscos:

1. Crie uma nova key com os mesmos escopos
2. Atualize suas aplicações para usar a nova key
3. Verifique se a nova key funciona corretamente
4. Revogue a key antiga

Monitorando Uso

Monitore o uso da sua API key no Backoffice para detectar:

• Padrões de requisição incomuns
• Requisições de endereços IP inesperados
• Tentativas de autenticação falhadas

Respostas de Erro

Código de Erro	Status HTTP	Descrição
MISSING_API_KEY	401	Header X-API-Key não fornecido
INVALID_FORMAT	401	API key não corresponde ao formato esperado
INVALID_KEY	401	API key não encontrada ou inválida
KEY_EXPIRED	401	API key passou da data de expiração
KEY_REVOKED	401	API key foi revogada
INSUFFICIENT_SCOPE	403	API key não possui escopo necessário para o endpoint

Veja Tratamento de Erros para mais detalhes sobre como lidar com erros.