Authenticate with the API.

v1.0.0

Access to the API is by Bearer Tokens. The process is somewhat similar to OAuth2.0, but with some changes to improve security.

You must first log into the firework online application and create a new Application in the Profile > API page. (You will need your PIN digits and 2-Factor Authentication device).
Give your application a Name and select the scope/permissions you need the application to have (more on Scopes below).
You will be provided with three pieces of information - the App Refresh Token, Client ID and Client Key. You need to take note of the Client Key when it is displayed - it will not be shown again.

You now use these pieces of data to retrieve a short-term Access Token which you can use to access the API. The Access Token expires within a relatively short time, so even if it is compromised, the attacker will not have long to use it. The Client Key is the most important piece of information to keep secret. This should only ever be stored on a backend server, and never in a front end client or mobile app.

If you ever accidentally reveal the Client Key (or accidentally commit it to Github for instance) it is vital that you log into firework online and delete/recreate the App Tokens as soon as possible. Anyone who has these three pieces of data can access the API to view your data and set up payments from your account (depending on the scope of the tokens).

Once you have the access token, pass it as a header for every call, like so:

Authorization: Bearer $ACCESS_TOKEN

Whenever it expires, create a new nonce and get a new access token again.

Input

{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "The Client ID for this API Application"
    },
    "clientSecret": {
      "type": "string",
      "description": "The SHA256 hash of the nonce above and the app’s Client Key. The Client Key will only be shown to you when you create the app, so don’t forget to save it somewhere safe. SECRET=( `/bin/echo -n $NONCE$CLIENT_KEY | sha256sum` )."
    },
    "grantType": {
      "type": "string",
      "description": "Always `AccessToken`. (This will change to `refresh_token` in a future release.)",
      "enum": [
        "AccessToken"
      ]
    },
    "nonce": {
      "type": "integer",
      "format": "int64",
      "description": "A random non-repeating number used as a salt for the `clientSecret` below. The simplest nonce is a unix time."
    },
    "refreshToken": {
      "type": "string",
      "description": "The Refresh Token for this API Application"
    }
  }
}

Output

{
  "type": "object",
  "properties": {
    "accessToken": {
      "type": "string",
      "description": "The App Bearer Access Token you can use in further API calls."
    },
    "apiApplicationId": {
      "type": "integer",
      "format": "int64",
      "description": "The ID of the application you are using."
    },
    "businessId": {
      "type": "integer",
      "format": "int64",
      "description": "The business ID for the business."
    },
    "expiry": {
      "type": "string",
      "format": "date-time",
      "description": "The expiry date and time for this token (ISO-8601)."
    },
    "permissions": {
      "type": "array",
      "description": "The permissions assigned to the Access Token as an array of strings. This provides information on what API access it is allowed. See the section on Scope below.",
      "items": {
        "type": "string"
      }
    }
  }
}