Pierwsze kroki
Uwierzytelnianie i uprawnienia
Każde wywołanie zawiera klucz API. Klucz daje dostęp do jednej przestrzeni roboczej, pozwala na to, co przewidują jego uprawnienia, i może wygasnąć.
Wysyłanie klucza
Wysyłaj klucz jako token Bearer. Narzędzia, które potrafią wypełnić tylko nagłówek o określonej nazwie, mogą zamiast tego użyć X-Api-Key. W obu przypadkach to ten sam klucz.
GET /api/v1/events HTTP/1.1
Host: attendbeacon.com
Authorization: Bearer abk_k7m2qx9vtw4p_...Klucz składa się z abk_, dwunastu znaków, podkreślenia i 43-znakowego sekretu. Te dwanaście znaków to jego prefiks: przestrzeń robocza go pokazuje, aby dało się odróżnić klucze, a aktywność kluczy właśnie po nim je nazywa. Skanery sekretów rozpoznają znacznik abk_, więc klucz przez pomyłkę wypchnięty do repozytorium łatwo znaleźć.
Odpowiadamy tylko przez HTTPS. Nie ma ciasteczek ani sesji: każde żądanie jest niezależne.
Do czego klucz ma dostęp
Klucz należy do jednej przestrzeni roboczej i nie sięga nigdzie indziej. Wydarzenie, uczestnik lub webhook innej przestrzeni roboczej zwraca 404, dokładnie tak, jakby nie istniał. Dzięki temu klucz nigdy nie dowie się, co ma inny organizator.
Przestrzeń demonstracyjna nie ma własnych kluczy. Aby wypróbować zapisy, utwórz własną przestrzeń roboczą. Odczyty Beacon Summit w tej dokumentacji pokazują prawdziwe dane wersji demonstracyjnej.
Uprawnienia
Uprawnienie (scope) to obszar i rodzaj dostępu: events:read, attendees:write. Daj kluczowi tylko te uprawnienia, których potrzebuje jego oprogramowanie. Wtedy klucz, który wycieknie, nie zdradzi niczego więcej.
- Zapis obejmuje odczyt w tym samym obszarze: klucz z
program:writemoże też odczytywać sesje. people:readto osobne uprawnienie. Bez niego osoby są tylko identyfikatorami: uczestnik ma bilet, status i godzinę wejścia, ale nie ma imienia i nazwiska, adresu, firmy ani odpowiedzi, apersonalDatama wartośćwithheld. Liczby, sprzedaż i program nie wymagają danych osób.- Wywołanie wymagające uprawnienia, którego klucz nie ma, zwraca
403z"code": "missingScope", a pole"scope"wskazuje, czego brakuje. Uprawnienia wybiera się przy tworzeniu klucza. Jeśli potrzebujesz innych, utwórz nowy klucz.
| Uprawnienie | Pozwala na |
|---|---|
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. |
Przestrzeń robocza oferuje cztery punkty wyjścia: Pulpit (wydarzenia, bilety, zamówienia, check-iny i program, tylko odczyt), Power Automate lub Zapier (to, czego używają łącznik i aplikacja Zapier), Asystent AI (odczyt wszystkiego, łącznie z danymi osób) oraz Wszystko.
Klucze utworzone przed październikiem 2026
Klucze sprzed wprowadzenia uprawnień według obszarów miały read i write. Zamieniono je na to, co wtedy oznaczały, i działają dokładnie tak jak wcześniej: read stało się każdym istniejącym wtedy odczytem (łącznie z danymi osób), a write stało się attendees:write i checkins:write. Żaden klucz nie zyskał nowych możliwości.
Wygasanie i unieważnianie
Klucz może wygasnąć po 30, 90, 180 lub 365 dniach albo nigdy. Wygasły klucz zwraca 401 z "code": "keyExpired". Utwórz nowy klucz przed datą wygaśnięcia starego i podmień go – nic nie przestanie działać.
Unieważnienie klucza w przestrzeni roboczej natychmiast go wyłącza (keyRevoked). Subskrypcje przepływów Power Automate i Zapów utworzone tym kluczem są usuwane razem z nim, bo same nie mogłyby się już wypisać.
Aktywność kluczy
Integracje › API & MCP › Aktywność kluczy pokazuje każde wywołanie, jakie klucz wykonał przez API lub serwer MCP w ciągu ostatnich 90 dni: kiedy, jaką operację (ścieżkę, np. GET /events/{eventId}/attendees, albo narzędzie MCP), z jaką odpowiedzią, jak długo trwało i z jakiego adresu. Nigdy nie zapisujemy ciągu zapytania, treści żądania ani odpowiedzi: adres uczestnika użyty w wyszukiwaniu nie może trafić do dziennika. Odrzucone wywołania też tam są, razem z kodem, więc gdy przepływ przestaje działać, właśnie tam najpierw szukaj missingScope lub rateLimited.
Zmiany wprowadzone kluczem pojawiają się również w dzienniku aktywności przestrzeni roboczej, podpisane nazwą klucza: „API key abk_k7m2qx9vtw4p (Attendee sync for the CRM)”.
Bezpieczeństwo kluczy
- Jeden klucz na każdy program, nazwany jego nazwą. Wtedy możesz unieważnić jeden, nie zatrzymując pozostałych.
- Przechowuj klucze w magazynie sekretów (Key Vault, sekrety twojego CI, menedżer haseł), nigdy w kodzie ani w repozytorium.
- Nigdy nie wysyłaj klucza do przeglądarki. Przycisk Wypróbuj w tej dokumentacji to wyjątek, na który decydujesz się świadomie: klucz zostaje w pamięci tej strony i trafia wyłącznie do attendbeacon.com.
- Ustawiaj kluczom datę wygaśnięcia i unieważniaj te, których według listy aktywności nikt nie używa.