Guides: Authentication

Authentication for Blockset is handled entirely using JSON Web Tokens (JWTs) and three object types:

  1. Accounts - this level is service-provider level authentication. It is used to manage push notification clients and billing. For example, “FancyCorp” will have a single Account. Generally accounts are maintained by BRD and the service provider will not have to interact with it much besides for testing. By default, self-serve and free accounts will come with very low rate limits.
  2. Client - these are created and owned by Accounts and represent an application created by the Account holders. For example, the “FancyCorp” Account may have two Clients: “FancyCorp iOS” and “FancyCorp Android”. Clients should only be created once per app.
  3. User - these are created by Clients and represent individual users of the client. For example, for every installation of “FancyCorp Android” - an automated background process will create and maintain a User token for that person.

Each of these principal types have their own JWT and UUID. The Account and Client JWTs are provided by the server. The User JWT is signed client-side using the user’s own signing key. This schema (client-side-generated JWTs) allows for password-less API access.

Authenticating: Generating a "User JWT"

Given a Client JWT, you may create a user using POST /users/token which returns a hash including a user UUID and your client UUID.

Using these, you create a JWT on-device with the following:

header = { "alg": "ES256", "typ": "JWT" }
payload = {
  "sub": user_response.token, // UUID for user
  "iat": 1564684703, // now, in seconds since epoch
  "exp": 1564694703, // expiry time, in the future
  "brd:ct": "usr",
  "brd:cli": user_response.client_token, // UUID for client
}

Then sign this JWT with the private key associated with the public key you passed to POST /users/token. If you're rolling your own JWT implementation, make sure the signature is JOSE encoded, not DER. Check your JWTs using our JWT tool, and validate your cryptographic functions using our cryptographic reference implementations.

Here is some Javascript sample code: user-jwt.js

EU Flag

This site uses cookies for the purposes outlined in our cookie policy. Your consent is assumed by dismissing this banner.