Skip to content

Developer Manual

The B.A.M API is a RESTful web service with JSON type request/responses. The API domains are:

There are different levels of service integration, depending on whether or not you want to host your blockchain nodes. For maximized security and performance, B.A.M offers bigger organizers (or agencies representing multiple organizers) the possibility to host their blockchain nodes separately from others by making them a tenant. In that way, API calls made for that organizers are routed based on the tenant name.

For example, if you're a tenant named Eventspace, the requests for creating, listing events, placing orders, downloading tickets, or sending transactions to the blockchain will be routed to https://eventspace.api.bam.fan (for the dev environment it's https://eventspace.develop.bam.fan).

If you're a smaller organizer who wishes to create events and issue tickets for them, you can use the B.A.M tenant called catapult (for the dev environment it's org1).

The tenant (also named organization) to which you send your requests depends on this information. To determine to which tenant you need to send your requests, check the organization_name field in the [GET account/v1/organizer/:id] response. If you are an organization, hosting your nodes and such, this would be your organization_name.

The System has several organizations (which host their own blockchain nodes) and each organization can have several organizers belonging to them.

System Overview

The diagram below describes the system in a nutshell. User management, venue data, and other services are global endpoints that map to any tenant.

Each tenant has its own events, orders, blockchain with required certificates, reporting data, and other services for the specific use and manipulation of events on the specific tenant.

System overview

All tickets are linked to a user. Ticket operations are signed by the private key which you can obtain by creating a wallet for a user after creation.

The usual way of interacting with the system is through our mobile app which needs to have the appropriate certificate imported.

API conventions

Format

All requests MUST be made with the correct JSON mime type in the header: Content-Type: application/json

Requests made from the mobile application require the x-device-id header, specified in the user's account.

Some endpoints need special headers, so be sure to read the Swagger docs in detail before using them.

The response body contains the result (in case of OK 2xx return code) inside the data field.

For example:

Request to POST payment/v1/payment?order_id=1234

Will get a response in the format:

{
    "data": {
        ...
    }
}

Timestamps both in requests and responses are given in ISO 8601 format.

Versioning

API versioning is route-based. After the first route segment that maps to the correct service used (account, event, reporting, etc.) comes the version segment.

The API version is currently v1 on all services.

Authentication

B.A.M services use a RSA-signed JWT for authentication and authorization. A valid JWT can be obtained by:

The JWT is sent in the Authorization header: Authorization: Bearer {JWT}

Requests that require authentication but don't send a valid JWT result in a 401 Unauthorized response.

Back to top