Primeiros passos
Autenticação e âmbitos
Cada chamada leva uma chave de API. Uma chave chega a uma área de trabalho, faz o que os seus âmbitos permitem e pode expirar.
Enviar a chave
Envie a chave como token Bearer. Ferramentas que só conseguem preencher um cabeçalho com nome podem usar X-Api-Key em alternativa; é a mesma chave nos dois casos.
GET /api/v1/events HTTP/1.1
Host: attendbeacon.com
Authorization: Bearer abk_k7m2qx9vtw4p_...Uma chave tem o formato abk_, doze caracteres, um sublinhado e um segredo de 43. Os doze caracteres são o seu prefixo: a área de trabalho mostra-os para que possa distinguir as chaves, e a atividade das chaves identifica as chaves por eles. Os scanners de segredos reconhecem o marcador abk_, por isso uma chave enviada por engano para um repositório é fácil de encontrar.
Só é respondido HTTPS. Não há cookies nem sessões: cada pedido é independente.
A que chega uma chave
Uma chave pertence a uma área de trabalho e não chega a mais nada. Um evento, um participante ou um webhook de outra área de trabalho responde 404, exatamente como se não existisse, por isso uma chave nunca pode saber o que outro organizador tem.
A área de trabalho de demonstração não tem chaves próprias. Crie a sua própria área de trabalho para experimentar escritas; as leituras do Beacon Summit nesta documentação são dados reais da demonstração.
Âmbitos
Um âmbito é uma área e um acesso: events:read, attendees:write. Dê a uma chave os âmbitos de que o seu software precisa e nada mais, para que uma chave divulgada não revele mais do que isso.
- Escrever inclui ler na mesma área: uma chave com
program:writetambém pode ler sessões. people:readé um âmbito à parte. Sem ele, as pessoas são ids: um participante tem um bilhete, um estado e uma hora de entrada, mas não tem nome, endereço, empresa nem respostas, epersonalDataindicawithheld. Contagens, vendas e o programa não precisam de nenhuma pessoa.- Uma chamada que precisa de um âmbito que a chave não tem responde
403com"code": "missingScope"e"scope"a indicar o que falta. Os âmbitos escolhem-se quando a chave é criada; para âmbitos diferentes, crie uma nova chave.
| Âmbito | Permite |
|---|---|
events:read | Events: the list, details, statistics, registration questions and doors. |
events:write | Create draft events, change their basics and publish or unpublish them. |
tickets:read | Ticket types, add-ons and discount codes, with what is sold. |
tickets:write | Change a ticket type's capacity and sales window, and create discount codes. |
orders:read | Orders and their money, and the sales pace. |
attendees:read | Registrations and attendees: ticket, status and check-in; names and answers need people:read too. |
attendees:write | Register people with a free ticket and cancel tickets, as the workspace does. |
checkins:read | Door scans and check-in counts. |
checkins:write | Check attendees in at a door, by the scanner's rules. |
program:read | Sessions, rooms, tracks and speakers. |
program:write | Add and change sessions on the agenda. |
sponsors:read | Sponsors, exhibitors, their levels and consented leads. |
cfp:read | Call-for-speakers submissions and their status. |
crew:read | Crew, volunteers, roles and shifts. |
surveys:read | Surveys, session ratings and their results, never who answered. |
finance:read | Invoices, credit notes and the budget summary. |
sharekit:read | The share kit's leaderboard of speakers, sponsors and attendees who spread the word. |
communities:read | Communities and their members. |
webhooks:read | Webhook endpoints, their deliveries, the event types and subscriptions for automation platforms. |
webhooks:write | Add, change, test and remove webhook endpoints. |
people:read | Personal data in any of the above: names, email addresses, companies and answers. Without it, people are ids only. |
A área de trabalho oferece quatro pontos de partida: Painel (eventos, bilhetes, encomendas, registos de entrada e o programa, só leitura), Power Automate ou Zapier (o que o conector e a app do Zapier usam), Assistente de IA (tudo para ler, incluindo pessoas) e Tudo.
Chaves criadas antes de outubro de 2026
As chaves anteriores aos âmbitos por área tinham read e write. Foram reescritas para o que esses valores significavam e continuam a funcionar exatamente como antes: read passou a ser todas as leituras que existiam (incluindo pessoas) e write passou a ser attendees:write e checkins:write. Nenhuma ganhou novos poderes.
Validade e revogação
Uma chave pode expirar após 30, 90, 180 ou 365 dias, ou nunca. Uma chave expirada responde 401 com "code": "keyExpired"; crie a nova chave antes do dia em que a antiga expira e faça a troca, e nada para.
Revogar uma chave na área de trabalho desativa-a de imediato (keyRevoked). Os fluxos do Power Automate e os Zaps que subscreveu deixam de estar subscritos com ela, porque já não conseguiriam cancelar a subscrição sozinhos.
A atividade das chaves
Integrações › API & MCP › Atividade das chaves lista cada chamada que uma chave fez através da API ou do servidor MCP nos últimos 90 dias: quando, que operação (a rota, como GET /events/{eventId}/attendees, ou a ferramenta MCP), como foi respondida, quanto tempo demorou e de que endereço veio. Nunca uma query string, um corpo ou uma resposta: o endereço de um participante numa pesquisa não deve ficar num registo. As chamadas recusadas também lá estão, com o seu código, por isso missingScope ou rateLimited é o primeiro sítio onde procurar quando um fluxo para.
As alterações feitas com uma chave também aparecem no registo de atividade da área de trabalho, com o nome da chave: «API key abk_k7m2qx9vtw4p (Sincronização de participantes para o CRM)».
Manter as chaves seguras
- Uma chave por software, com o nome dele, para poder revogar uma sem parar as outras.
- Guarde as chaves num cofre de segredos (Key Vault, os segredos do seu CI, um gestor de palavras-passe), nunca no código nem num repositório.
- Nunca envie uma chave para um navegador. O botão Experimentar desta documentação é a exceção que faz por sua conta: a chave fica na memória dessa página e só vai para attendbeacon.com.
- Dê uma validade às chaves e revogue as que a lista de atividade mostra que ninguém usa.