Authorization to Boldem API

Michal Krejčí

16. October 2023

To call individual Boldem API endpoints, you need to complete the authorization process. The authorization procedure, examples, and prerequisites for use are provided below.

Prerequisites

Created Boldem account .
Paid Boldem Profi plan.
API key (client ID and secret key) generated in your Boldem account which you will manage using the API interface.
Access token and refresh token obtainable by calling the appropriate endpoint and using the API key.
Complete overview of all Boldem API endpoints which can be found at https://api.boldem.cz/.
Optionally, one of the API testing tools such as Postman, Insomnia, or httpiness.

Generating API key

Log into your Boldem account.
Go to Settings/API.
Click New API key.
Enter the name of the key for your reference.
A dialog displaying the API key information, including the Client ID and Client Secret Key, will appear. Please copy and securely store the data in a safe location.

How to use access and refresh tokens

The Boldem API uses an access and refresh token system within the OAuth protocol, ensuring security and convenience when accessing its resources via the API interface.

Access token is a credential that grants a user access to specific resources (Boldem API endpoints) for a specific period of time (in this case, 60 minutes).

Refresh token, on the other hand, has a longer lifespan and serves the purpose of generating a new access token when the previous one expires. This functionality ensures that users can stay authenticated without the need for repeated manual login.

Here are some best practices and recommendations on how to use tokens properly:

Generating a new token on first login: When the user first logs into the application, make an endpoint call to create a new access token. Use this token for all subsequent calls.
Secure token storage: You should store both the access token and the refresh token securely on the client side. Depending on your application’s specific needs and potential threats, this can be achieved through in-memory storage, local storage, or secure cookies.
Token refresh before expiry: There is no need to track the exact duration of token usage; you can provide a safety margin. For example, if a Boldem access token expires in 60 minutes, consider refreshing it every 50 minutes. This approach ensures that there is no risk of the access token expiring during an ongoing request.
Using a refresh token for new access tokens: If the access token expires, use the refresh token to generate a new access token. This process occurs smoothly, eliminating the need for the user to manually log in again.
Troubleshooting possible failure to generate refresh token: If you are unable to generate a new access token using a refresh token (the refresh token has expired or been revoked), you should redirect the user to the login page for re-authentication.
Revoking an old refresh token after use: As an added security measure, consider invalidating old refresh tokens once they have been used to generate a new token. This approach ensures that if an attacker gains access to a refresh token, they can use it only once, and a legitimate user will promptly notice any suspicious activity after logging out
Regular replacement of refresh tokens: Another recommended practice is to replace refresh tokens regularly to minimize potential damage in the event of a compromise.

These practices create a balance between user convenience, reducing the need for frequent logins, and ensuring security.

Creating access token

To call individual API endpoints, you will need to generate an access token (access_token) using the API key. This access token remains valid for 60 minutes and must be refreshed after that period.

For effective testing of the Boldem API, we suggest using tools like Postman, Insomnia, or httpiness. You can import all the endpoints from https://api.boldem.cz/ into these tools and test them before integrating them into your own application.

Access tokens are obtained by making a POST request to the /v1/oauth endpoint. Below are some examples of these requests.

Replace the values in the client_id and client_secret parameters with values copied from your Boldem account.

Example of creating access token in Python

import http.client
import json

conn = http.client.HTTPSConnection("api.boldem.cz")
payload = json.dumps({
  "client_id": "e9579f436bbd4ec1a1ebxcbb1aqq12a8",
  "client_secret": "qwDpL5aA8FaFUD6FRWHb2oceOMCJWpTHiyGINbGKGCTBNeXu8OjH8HlAXCOl97Fc"
})
headers = {
  'Content-Type': 'application/json'
}
conn.request("POST", "/v1/oauth", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Example of creating access token in Node.Js

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.boldem.cz',
  'path': '/v1/oauth',
  'headers': {
    'Content-Type': 'application/json'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "client_id": "e9579f436bbd4ec1a1ebxcbb1aqq12a8",
  "client_secret": "qwDpL5aA8FaFUD6FRWHb2oceOMCJWpTHiyGINbGKGCTBNeXu8OjH8HlAXCOl97Fc"
});

req.write(postData);

req.end();

Example of creating access token in PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.boldem.en/v1/oauth',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "client_id": "e9579f436bbd4ec1a1ebxcbb1aqq12a8",
  "client_secret": "qwDpL5aA8FaFUD6FRWHb2oceOMCJWpTHiyGINbGKGCTBNeXu8OjH8HlAXCOl97Fc"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

Creating access token – call result

When the above endpoint is called, you should receive a JSON output containing an access_token and a refresh_token:

{
    "access_token": "RC8Z4F4ctUtJu7JDCK5tunIAuSb2pNMbEFjjSfCizgXDQqaCgcoYluCvR0EN5C8zotxb1r9Us0WiWKuflxXUdUXxEeIkB1Q39I8w6U8tDtAn7wMw7iiL7mNTRVw60gDBeCcsPHFGbPbZsWc9cL3vI9DjqpEPFUE78WVVcepdckAt7EDlHr5sNkDbFlMz6OKqYVNDHSbLkIfjvXACiMrikJMiJyAg4",
    "expires_in": 3600,
    "valid_to": "2023-07-14T13:43:36.0353963Z",
    "token_type": "Bearer",
    "refresh_token": "4Nos3O2r6enN9LADZaDfyybHZ4aOcjSD"
}

Refreshing access token

Since the access token is valid for no more than 60 minutes, it needs to be refreshed in time. To do that, use the /v1/oauth/refresh endpoint. See below for example calls.

Replace the values in access_token and refresh_token with the values copied from the call result you received when you generated the new access token.

Example of access token refresh in Python

import http.client
import json

conn = http.client.HTTPSConnection("api.boldem.cz")
payload = json.dumps({
  "access_token": "RC8Z4F4ctUtJu7JDCK5tunIAuSb2pNMbEFjjSfCizgXDQqaCgcoYluCvR0EN5C8zotxb1r9Us0WiWKuflxXUdUXxEeIkB1Q39I8w6U8tDtAn7wMw7iiL7mNTRVw60gDBeCcsPHFGbPbZsWc9cL3vI9DjqpEPFUE78WVVcepdckAt7EDlHr5sNkDbFlMz6OKqYVNDHSbLkIfjvXACiMrikJMiJyAg4",
  "refresh_token": "4Nos3O2r6enN9LADZaDfyybHZ4aOcjSD"
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json'
}
conn.request("POST", "/v1/oauth/refresh", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Example of access token refresh in Node.Js

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.boldem.cz',
  'path': '/v1/oauth/refresh',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/problem+json'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "access_token": "RC8Z4F4ctUtJu7JDCK5tunIAuSb2pNMbEFjjSfCizgXDQqaCgcoYluCvR0EN5C8zotxb1r9Us0WiWKuflxXUdUXxEeIkB1Q39I8w6U8tDtAn7wMw7iiL7mNTRVw60gDBeCcsPHFGbPbZsWc9cL3vI9DjqpEPFUE78WVVcepdckAt7EDlHr5sNkDbFlMz6OKqYVNDHSbLkIfjvXACiMrikJMiJyAg4",
  "refresh_token": "4Nos3O2r6enN9LADZaDfyybHZ4aOcjSD"
});

req.write(postData);

req.end();

Example of access token refresh in PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.boldem.cz/v1/oauth/refresh',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "access_token": "RC8Z4F4ctUtJu7JDCK5tunIAuSb2pNMbEFjjSfCizgXDQqaCgcoYluCvR0EN5C8zotxb1r9Us0WiWKuflxXUdUXxEeIkB1Q39I8w6U8tDtAn7wMw7iiL7mNTRVw60gDBeCcsPHFGbPbZsWc9cL3vI9DjqpEPFUE78WVVcepdckAt7EDlHr5sNkDbFlMz6OKqYVNDHSbLkIfjvXACiMrikJMiJyAg4",
  "refresh_token": "4Nos3O2r6enN9LADZaDfyybHZ4aOcjSD"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/problem+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Access token refresh – call result

When the above endpoint is called, you should receive a JSON output containing a new access_token and a refresh_token:

{
    "access_token": "3w6G3bacJLp3YwiOEiyCvTQx6RPntkx8Z7Kwx5nrZiFvAEtYGeSNDWOKqaZTgNvPOoQ947E4pRfxpe7u5kj5oRJDCFXqXrEb1xfFpvrXNdzh3YsCnqkRwJYnHvGR3231uJEJoo1jTbtFVyn621YMk648QHDY6839mNzT1B3YrGnZvENWcGVKd3p7PI1B9JtO3QzRLnPONPCEbHD1Nu8XLiTxtE9Iq",
    "expires_in": 3600,
    "valid_to": "2023-07-14T14:56:15.3827468Z",
    "token_type": "Bearer",
    "refresh_token": "WFCwG66ho9Zbx0CBR6bFat2YR4Czoxln"
}

Revoking specific refresh token

To revoke a specific refresh token, call the /v1/oauth/revoke endpoint. See below for examples of calls.

Replace the values in access_token and refresh_token with the values copied from the call result you received when you generated these tokens.

Example of revoking specific refresh token in Node.Js

var https = require('follow-redirects').https;
var fs = require('fs');

var options = {
  'method': 'POST',
  'hostname': 'api.boldem.cz',
  'path': '/v1/oauth/revoke',
  'headers': {
    'Content-Type': 'application/json',
    'Accept': 'application/problem+json'
  },
  'maxRedirects': 20
};

var req = https.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function (chunk) {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });

  res.on("error", function (error) {
    console.error(error);
  });
});

var postData = JSON.stringify({
  "access_token": "3w6G3bacJLp3YwiOEiyCvTQx6RPntkx8Z7Kwx5nrZiFvAEtYGeSNDWOKqaZTgNvPOoQ947E4pRfxpe7u5kj5oRJDCFXqXrEb1xfFpvrXNdzh3YsCnqkRwJYnHvGR3231uJEJoo1jTbtFVyn621YMk648QHDY6839mNzT1B3YrGnZvENWcGVKd3p7PI1B9JtO3QzRLnPONPCEbHD1Nu8XLiTxtE9Iq",
  "refresh_token": "WFCwG66ho9Zbx0CBR6bFat2YR4Czoxln"
});

req.write(postData);

req.end();

Example of revoking specific refresh token in Python

import http.client
import json

conn = http.client.HTTPSConnection("api.boldem.cz")
payload = json.dumps({
  "access_token": "3w6G3bacJLp3YwiOEiyCvTQx6RPntkx8Z7Kwx5nrZiFvAEtYGeSNDWOKqaZTgNvPOoQ947E4pRfxpe7u5kj5oRJDCFXqXrEb1xfFpvrXNdzh3YsCnqkRwJYnHvGR3231uJEJoo1jTbtFVyn621YMk648QHDY6839mNzT1B3YrGnZvENWcGVKd3p7PI1B9JtO3QzRLnPONPCEbHD1Nu8XLiTxtE9Iq",
  "refresh_token": "WFCwG66ho9Zbx0CBR6bFat2YR4Czoxln"
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json'
}
conn.request("POST", "/v1/oauth/revoke", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Example of revoking specific refresh token in PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.boldem.cz/v1/oauth/revoke',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "access_token": "3w6G3bacJLp3YwiOEiyCvTQx6RPntkx8Z7Kwx5nrZiFvAEtYGeSNDWOKqaZTgNvPOoQ947E4pRfxpe7u5kj5oRJDCFXqXrEb1xfFpvrXNdzh3YsCnqkRwJYnHvGR3231uJEJoo1jTbtFVyn621YMk648QHDY6839mNzT1B3YrGnZvENWcGVKd3p7PI1B9JtO3QzRLnPONPCEbHD1Nu8XLiTxtE9Iq",
  "refresh_token": "WFCwG66ho9Zbx0CBR6bFat2YR4Czoxln"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/problem+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

Revoking specific refresh token – call result

After calling the above endpoint, in a successful scenario, you should expect to receive a 204 return code with no content.

Signing out and revoking all refresh tokens

To unsubscribe the user and revoke all refresh tokens, call the /v1/oauth/signout endpoint without any additional parameters.