Skip to main content

Access Tokens

When working with Space Blocks, you will come across different types of access tokens. This documents clarifies, which ones to use when. The Space Blocks Access Token is a JSON Web Token (JWT), which gets issues by the Space Blocks Token Manager.

Regular Space Blocks Access Token​

A regular Space Blocks Access Token gets requested by an OAuth Client by using its client credentials. The regular Space Blocks Access Token should only be used by your backend services to comminicate with the Space Blocks APIs directly.

This Access Token is usually used for administrative work on your servers.

Structure​

When decoding the JWT, its content will look like this.

{
  "aud": [
    "https://localhost:5001/"
  ],
  "client_id": "foo",
  "exp": 1659711999,
  "ext": {
    "spaceblocks_project_id": "bar",
    "spaceblocks_environment_id": "lorem",
    "spaceblocks_tenant_id": "foo",
    "app_tenant_id": "",
    "app_subject_id": ""
  },
  "iat": 1659708398,
  "iss": "https://auth.spaceblocks.cloud/issuer/",
  "jti": "b23e7969-2f24-4622-8513-e34858696f1e",
  "nbf": 1659708398,
  "scp": [
    "foo:bar"
  ],
  "sub": "foo"
}

Requesting a Regular Space Blocks Access Token​

Please see the Authentication Flow for Backend Services for details on how to request a Regular Space Blocks Access Token.

Impersonated Space Blocks Access Token​

Impersonated Space Blocks Access Tokens are used to communicate with a Space Block directly in the name of on of your subjects (e.g. users, clients, ...). This scenario is usually used for frontend services, which need to communicate with a Space Block directly.

These tokens should get issued by your backend services, which are capable of holding secrets securely. The backend service should then pass the token to the frontend service, which can then use it to communicate with the Space Blocks API.

When your frontends request an Impersonated Space Blocks Access Token at your backend, your backend is responsible for authenticating your users. Afterwards, it can request an Access Token for your user (using the Subject ID and Tenant ID form your systems in the format that you use) and return it to the frontend.

When sending a request to a Space Block from your frontend with this Impersonated Access Token, the Space Block will perform the actions in the name of the impersonated subject (as it appears in the token payload at ext.app_tenant_id and ext.app_subject_id).

Structure​

When decoding the JWT, its content will look like this.

{
  "aud": [
    "https://localhost:5001/"
  ],
  "client_id": "foo",
  "exp": 1659711999,
  "ext": {
    "spaceblocks_project_id": "bar",
    "spaceblocks_environment_id": "lorem",
    "spaceblocks_tenant_id": "foo",
    "app_tenant_id": "tenant-123",
    "app_subject_id": "user-123"
  },
  "iat": 1659708398,
  "iss": "https://auth.spaceblocks.cloud/issuer/",
  "jti": "b23e7969-2f24-4622-8513-e34858696f1e",
  "nbf": 1659708398,
  "scp": [
    "foo:bar"
  ],
  "sub": "foo"
}

Requesting an Impersonated Space Blocks Access Token​

Please see the Authentication Flow for Frontends for details on how to request an Impersonated Space Blocks Access Token.