# Developer API

Source: https://blocklive.io/docs/developers

Read your events, ticket types, attendees and check-ins from your own app: a
door or badge app, a CRM sync, a dashboard.

> The developer API is in a pilot. An organization's owner switches
> developer access on for the organization (see
> [switching it on](#switching-it-on)). For a team that isn't part of an
> organization, email [support@blocklive.io](mailto:support@blocklive.io).

## What it does

-   It reads. Every endpoint is a `GET` under `https://blocklive.io/api/v1` and
    answers JSON.
-   It covers events, ticket types, attendees (one row per ticket holder) and
    the door's check-ins and check-outs.
-   It doesn't check guests in, add guests or change anything. Check-in stays in
    Blocklive's door app.

## Get a key

An API key comes from the organizer: an admin of the organization or team, in
Blocklive's admin, on its **Developer** page. When the key is made, the
organizer chooses which events it reads and which attendee details it gets.

The key is shown once. Blocklive keeps only a hash of it, so a lost key can't be
shown again: ask the organizer for a new one.

## Switching it off and on

Developer access is on for every organization that has an owner: the
organization, every team in it (including teams that join later) and every one
of their events. The organization's owner switches it off and on. On the
organization's page, open **Security** and, by **Developer API**, press
**Turn off** or **Turn on**. While it's off, the **Developers** tab offers
**Turn on developer access**.

-   It covers the organization, every team in it and every one of their
    events. The owner makes and manages keys, developers and what developers
    may share at each of those levels.
-   Switching needs two-step verification and a sign-in in the last 15
    minutes. Blocklive asks you to sign in again if yours is older.
-   **Turn off** stops the keys of the organization, its teams and events at
    once. None is revoked, so they work again when it's turned back on. An
    organization its owner turned off stays off, even when its owner changes.
    A team that Blocklive switched on by itself keeps its own switch: email
    [support@blocklive.io](mailto:support@blocklive.io) to turn that off.
-   A team in no organization is off until Blocklive switches it on: email
    [support@blocklive.io](mailto:support@blocklive.io).

## Authenticate

Send the key as a bearer token on every request:

```http
Authorization: Bearer bl_live_<id>_<secret>
```

```sh
curl -H "Authorization: Bearer $BLOCKLIVE_API_KEY" https://blocklive.io/api/v1/events
```

> **Warning:** Keep the key on your server, in your app's secret settings.
> Never put it in a browser, a phone app or a repository. Anyone with the key
> can read what it reads.

-   A revoked or expired key gets `401 unauthorized`.
-   Keys made outside production start with `bl_test_` and only work there.

## What a key reads

Every key reads **events, ticket types and attendees by an anonymous ID**.
Attendee details are included only if the organizer shared them with the key:

| Detail                  | Field in the API       | Needs                   |
| ----------------------- | ---------------------- | ----------------------- |
| Email address           | `email`                |                         |
| Full name               | `name`                 |                         |
| Team person ID          | `team_person_id`       |                         |
| Company                 | `company`              |                         |
| Job title               | `job_title`            |                         |
| Organisation type       | `organisation_type`    |                         |
| Registration answers    | `registration_answers` |                         |
| Ticket types and access | `ticket_entitlements`  |                         |
| Ticket type names       | `ticket_type_names`    | Ticket types and access |
| Purchase status         | `purchase_state`       |                         |
| Venue check-in          | `checkin_state`        |                         |
| Check-in time           | `checkin_time`         | Venue check-in          |

Each answer lists what your key reads for that event in `shared_fields`.

## Endpoints

| Path                                         | Returns                                                  |
| -------------------------------------------- | -------------------------------------------------------- |
| `/events`                                    | The events your key can read, newest first               |
| `/events/{event_id}/ticket-types`            | The event's ticket types                                 |
| `/events/{event_id}/attendees`               | One row per ticket holder, with only the details shared  |
| `/events/{event_id}/attendees/{attendee_id}` | One attendee                                             |
| `/events/{event_id}/check-ins`               | Check-ins and check-outs in order (needs venue check-in) |

Fields, examples and paging are in [read endpoints](https://blocklive.io/docs/developers/reads). The rate limit
and every error code are in [limits and errors](https://blocklive.io/docs/developers/limits-and-errors).

## Privacy

-   A key reads only the details shared with it, only for its events, and only
    while developer access is on.
-   Attendees are identified by anonymous IDs made for each key and event.
-   Blocklive logs each request's time, key, endpoint, status and duration for
    90 days, never the data it returned.

## From your terminal

To read your events and guests yourself, signed in with your own account
instead of a key, use the [Blocklive CLI](https://blocklive.io/docs/developers/cli).

## Help

Email [support@blocklive.io](mailto:support@blocklive.io) with the `request_id`
of any error.