Skip to main content

​
Administrando API Keys

A segurança é um pilar fundamental da API MessageFy. Toda requisição é autenticada por uma chave de API — um token único que identifica sua aplicação e autoriza o acesso aos endpoints. Cada chave vive dentro de uma Account específica e só pode acessar os recursos daquela Account — esse isolamento é o que permite operar múltiplos departamentos ou clientes com segurança em uma mesma organization.

​
Para que serve uma API Key?

Toda requisição deve incluir uma API Key válida no header X-API-KEY. Sem ela, a requisição é rejeitada com 401 Unauthorized.
O alcance de uma chave é determinado pelo seu tipo, indicado no prefixo do token: org_ abrange toda a organization; acc_ fica restrita a uma única Account. Não existem permissões por scope — a segregação acontece pela combinação de tipo da chave e isolamento por Account.
Cada chave está vinculada a um resource plan, que define o limite de requisições por janela de tempo (limit requisições a cada seconds segundos). É esse plano — e não um conjunto de permissões — que controla a intensidade de uso da chave.
Cada chave tem um identificador único, e todas as requisições são registradas. Você consegue saber exatamente qual chave foi usada em cada ação — fundamental para auditoria de segurança e investigação de incidentes.
Se uma chave for comprometida, revogue-a imediatamente sem afetar as demais. Bem mais seguro do que compartilhar uma única credencial entre múltiplas aplicações.
Mantenha chaves distintas para desenvolvimento, staging e produção, cada uma com permissões e configurações apropriadas ao ambiente.

​
Tipos de chave

A chave de API tem seu tipo indicado pelo prefixo do token: Esse nível de acesso é exposto no campo type do retorno da chave, ao lado do plano de recursos que rege o rate limit:
​
string
Nível de acesso da chave. Reflete o prefixo do token (org_ para toda a organization, acc_ para uma única Account) e substitui qualquer noção de scopes.
​
object
Plano de recursos vinculado à chave, que define o rate limit.
​
integer
Número máximo de requisições permitidas dentro da janela.
​
integer
Duração da janela, em segundos (limit requisições a cada seconds segundos).
Use o endpoint /me para descobrir o tipo e as características da chave em uso — útil para validação inicial em pipelines de integração.

​
Como usar

Inclua a chave no header X-API-KEY de toda requisição:
Python
Node.js

​
Operações disponíveis

Listar API Keys

Lista as chaves emitidas para a Account atual, com filtros e paginação.

Buscar por ID

Recupera os detalhes de uma chave específica (sem expor o token).

Criar API Key

Gera uma nova chave. O token só é exibido uma vez — copie-o no momento da criação.

Atualizar API Key

Atualiza o nome e a descrição da chave. Não há ativar/desativar — para revogar, use a exclusão.

Revogar API Key

Revoga permanentemente o acesso de uma chave.

Sobre a chave atual

Endpoint /me para inspecionar a chave usada na requisição.

​
Boas práticas

Não exponha chaves em código client-side, repositórios públicos ou logs. Use variáveis de ambiente ou um cofre de segredos (Vault, AWS Secrets Manager, etc.) no servidor.
Uma chave por aplicação (ou por instância, em casos sensíveis). Isso granulariza o acesso, facilita auditoria por origem e permite revogação cirúrgica em caso de comprometimento.
Prefira chaves acc_, restritas a uma única Account, sempre que a aplicação não precisar operar toda a organization. Reserve chaves org_ para integrações que realmente exigem alcance global — assim você limita o impacto de um eventual vazamento.
Use chaves diferentes em cada ambiente. Uma chave de produção nunca deve aparecer em código de desenvolvimento — e vice-versa.
Mesmo sem suspeita de comprometimento, rotacione as chaves em intervalos regulares (90 dias é um bom ponto de partida). Mantenha as duas chaves ativas durante o período de transição.
O token completo da chave só é retornado na criação. Depois disso, somente o ID e os metadados ficam acessíveis. Se você perder o token, terá que revogar a chave e criar uma nova.