Skip to content

Getting Started

Pre-requisites

Before getting started, you will need to get an Application ID and an Application Secret from a GA SmartBuilding Administrator.

The Application ID will be used:

  • Client-side, alone
  • Server-side, alongside the Application Secret

Interacting with badge controllers

To be able to interact with a badge controller, you will need to get two elements:

  • A badge number
  • A server-generated signature
sequenceDiagram
  Your App->>+Badge Server: POST /v1/badge
  Badge Server->>+Your App: BadgeId and SAR Public Key
  Your App->>+Badge Server: POST /v1/signature
  Badge Server->>+Your App: Signed certificate

Getting a badge number

The request: POST /v1/badge

Badge numbers are distributed on a one per user device basis. To do so, the server will require three informations:

  • The Application ID of the application requesting the badge
  • A unique device identifier
  • The user's ID from your application
  • This ID will only be used to retrieve the badge and to allow you to reconciliate server-to-server interactions
  • Optional: Additional metadata used for analytics and troubleshooting
  • Optional: An invitation token

According to these requirements, the API call will need to happen once your user has been logged in into your application.

Getting a signature

The request: POST /v1/badge/sign

Once you got your badge number, you will need to sign it, according to the GA SmartBuilding requirements. Once this signature has been done, you will send it to our server in exchange to another signature you will need to store securely.

Server integration

Getting your application's badges

The request: GET /v1/badges

This will return the list of badges of your application

Creating an invitation

The request: POST /v1/invitation

This will return an invitation token alongside a badge id so you can send the invitation token to your user while setting up its access earlier with the provided badgeId.

sequenceDiagram
  Your Server->>+Badge Server: POST /v1/invitation
  Badge Server->>+Your Server: BadgeId and InvitationToken
  Your Server->>+SAR: Badge ID
  Your Server->>+Your App: Invitation Token
  Your App->>+Badge Server: Invitation Token
  Badge Server->>+Your App: Badge Id

Revoking an invitation

The request: PATCH /v1/invitation/:id/revoke

This will revoke the invitation, making the badge number available again.

Receiving webhooks

Our system allows your app to receive webhooks on the following events:

  • New badge creation (badge:created)

The webhook endpoint has to be sent to a GA SmartBuilding Administrator for setup.

Securing your webhooks

All the webhooks we send are secured using a Signature header, containing a signature of your payload using the following algorithm:

BASE64(
  SHA1(
    YOUR_APPLICATION_SECRET_KEY,
    JSON_STRINGIFY(
      YOUR_PAYLOAD
    )
  )
)