Authentication Flow

This document describes the authentication flow for Space Blocks. Communicating with most Space Blocks requires authentication via an Access Token in JSON Web Token (JWT) format. In the Developer Portal, OAuth Clients can be registered for each project and environments. The client credentials can be used to request an Access Token.

Warning

As the client's client_secret needs to be protected, you should never pass it to the frontend and the frontend should never request an Access Token directly at a Space Blocks Service. Refer to Requesting an Access Token for a frontend service for details on how to request Access Tokens for frontend services securely.

Requesting an Access Token

For a backend service

The most common scenario is requesting an Access Token for a backend service. In this case, your backend services need to communicate with the Space Blocks APIs directly.

When requesting a Space Blocks Access Token for a backend service that is controlled by you, the backend can request a token at the Space Bocks Token Manager directly. As backend services are capable of holding secrets securely, the backend can request the token using its client credentials (client_id and client_secret).

❶ Your backend requests a Space Blocks Access Token at the Space Blocks Token Service.

POST /token-manager/token HTTP/1.1
Host: auth.spaceblocks.cloud
Content-Type: application/json
apiKey <YOUR_API_KEY>

{
  "client_id": "abc",
  "client_secret": "xyz",
  "scope": "foo:bar"
}

❷ The Space Blocks Token Manager responds with a JWT token for the requesting client.

❸ Your backend service uses this token to send requests to a Space Block API

GET /bar HTTP/1.1
Host: foo.spaceblocks.cloud
Authorization: Bearer eyYUH6ajsds7ne8dJGHDke8ehYT5hbdidh... # <-- Space Blocks Access Token
Content-Type: application/json

❹ The Space Block identifies the requester as the client and responds.

For a frontend service

Some Space Blocks allow your frontends to communicate with them directly. This can be useful for performance, as it removes the need for a backend service to proxy requests or whenever a frontend needs to communicate with a Space Block directly via WebSockets.

For this scenario, your frontend needs to authenticate with an impersonated Space Blocks Access Token. As frontends should not hold client credentials, your backend should request this Access Token for your frontend and it's current user at the Space Blocks Token Manager.

For this, your need to implement a route for requesting Space Blocks Access Tokens at your backend services. which your frontend services can use to request a Space Blocks Access Token at your backend.

❶ Your frontend requests a Space Blocks Access Token at your backend.

Info

Authentication between your frontend and backend is up to you and is out of scope for this document.

❷ Your Backend identifies the subject (e.g. User ID) and optionally tenant (for example by checking the JWT) and requests an impersonated Space Blocks Access Token for the Frontend at the Space Blocks Token Service. The tenant_id and subject of this request should be set to the IDs you use in your system internally and are not the Tenant or User ID from you as a Space Blocks customer.

POST /token-manager/token HTTP/1.1
Host: auth.spaceblocks.cloud
Content-Type: application/json
apiKey: <YOUR_API_KEY>

{
  "client_id": "abc",
  "client_secret": "xyz",
  "scope": "foo:bar",
  "app_tenant_id": "foo",
  "app_subject_id": "bar"
}

❸ Space Blocks Token Manager responds with an impersonated Space Blocks Access Token that can be used by your frontend

❹ Your backend sends this impersonated Space Blocks Access Token to your frontend

❺ Your frontend can now send requests to Space Block X with the impersonated Space Blocks Access Token

GET /bar HTTP/1.1
Host: foo.spaceblocks.cloud
Authorization: Bearer eyYUH6ajsds7ne8dJGHDke8ehYT5hbdidh... # <-- impersonated Space Blocks Access Token
Content-Type: application/json

❻ Space Block X responds.

Example

To see, how and implementation of an Endpoint in your backend of issuing impersonated Access Tokens could look like, check out the How-to: Issue Impersonated Tokens docs.