Client Tokens

Client Tokens are JWT (JSON Web Tokens) that grant access to Bloq services, such as Nodes. There are two types of Client Tokens: Client Access Tokens and Client Refresh Tokens. These tokens are necessary for accounts but are not useful to interact with accounts endpoints. For more information about Bloq authentication, please check the Technical Reference.

TIP

Client tokens do not grant permissions for Accounts services. This makes the Client Access Token especially useful for sharing access to Nodes service with other users or applications, as the sensitive account billing and location information remain out-of-reach.

Generate Client Tokens

Before you can generate Client Tokens, you first need to setup your Bloq account and generate a pair of client keys. If you have not done so, please refer to the corresponding guides.

There are two ways to use the generate Client Tokens: using the Command Line Interface (CLI) or using the Accounts REST API.

Using the CLI

The CLI is a friendly tool and the easiest way to interact with Bloq services.

Open a terminal window and start you session by running bcl login.

The CLI has the client-keys command which enables you to generate a Client Access Tokenand a Client Refresh Token.

bcl client-token

? Do you want bcl to store your tokens locally for future usage? Yes
✔ Generated new tokens:
  * clientAccessToken: xxxxxx.xxxxxxxxxx.xxxxxx
  * refreshToken: xxxxxx.xxxxxxxxxx.xxxxxx

WARN  Be sure to copy and save these keys since it will not be possible to obtain them again.

Using the REST API

Creating Client Tokens using the REST API requires more steps than the CLI (which automates the whole authentication process).

As previously stated, a valid pair of client keys is required prior to using the service. The client keys let you generate your Client Access and Client Refresh tokens. The Client Acccess Token grants you access to the BloqNodes services, but for security reasons, the Client Acccess Token is a short term token (expires after one hour). When the token expires, you can use the Client Refresh Token (expires after one year but could be revoked) to get a new valid Client Acccess Token.

It is important to specify grantType as part of body request becuase this endpoint could also be used to refresh tokens. In this case the grantType value should be clientCredentials

Code Sample

curl -X POST https://accounts.bloq.cloud/auth/token
  -H 'Content-Type: application/json' \
  -d '{
  "grantType": "clientCredentials",
  "clientId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "clientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

Response

{
  "accessToken": "xxxxxx.xxxxxxxxxx.xxxxxx",
  "refreshToken": "xxxxxx.xxxxxxxxxx.xxxxxx"
}

Refreshing the Client Access Token

Since the Client Access Token is a short term JWT (JSON Web Token), when it expires, you have two alternatives: generate a new Client Access Token using your client-keys or generate a new access token using the Client Refresh Token. This latter process is what we refer to as a token refresh.

TIP

If you are using Bloq services through the CLI or JavaScript SDK you don't need to refresh tokens manually because they will do it for you in background. This process will be needed if you are using Bloq services through the REST API.\

To renew your Client Access Token, you simply need to call the Accounts REST API, /auth/token endpoint passing refreshToken and setting the corresponding grantType as part of your body request. In this case the grantType value should be refreshToken.

Code Sample

curl -X POST https://accounts.bloq.cloud/auth/token
  -H 'Content-Type: application/json' \
  -d '{
  "grantType": "refreshToken",
  "refreshToken": "xxxxxx.xxxxxxxxxx.xxxxxx",
}'

Response

{
  "accessToken": "xxxxxx.xxxxxxxxxx.xxxxxx"
}