Autorizace do rozhraní Boldem API

Michal Krejčí

14. července 2023

Abyste mohli volat jednotlivé koncové body rozhraní Boldem API, je zapotřebí se nejprve autorizovat. Postup autorizace, příklady a předpoklady použití najdete níže.

Předpoklady

Založený účet Boldem.
Zaplacený tarif Profi.
Klíč API (ID klienta a tajný klíč) vygenerovaný v účtu Boldem, který budete pomocí rozhraní API ovládat.
Přístupový token a obnovovací token, které získáte zavoláním příslušného koncového bodu a použitím klíče API.
Přehled všech koncových bodů Bodem API, který najdete na adrese https://api.boldem.cz/.
Volitelně některý z nástrojů k testování API, jako je Postman, Insomnia, nebo třeba httpiness.

Vygenerování klíče API

Přihlaste se do účtu Boldem.
Přejděte do Nastavení/API.
Klikněte na tlačítko Nový klíč API.
Zadejte název klíče pro vaši orientaci.
Zobrazí se dialog s údaji ke klíči API – ID klienta a Tajný klíč klienta. Oba údaje si zkopírujte a uložte na bezpečné místo.

Jak používat přístupové a obnovovací tokeny

V rozhraní Boldem API používáme systém přístupových a obnovovacích tokenů v rámci protokolu OAuth. Systém je navržen tak, aby poskytoval jak bezpečnost, tak pohodlí při přístupu ke zdrojům prostřednictvím rozhraní Boldem API.

Přístupový token je pověření, které uživateli poskytuje přístup ke konkrétním zdrojům (koncovým bodům Boldem API) na určitou dobu (v tomto případě 60 minut).

Obnovovací token má naopak delší životnost a slouží k vygenerování nového přístupového tokenu, jakmile platnost předchozího vyprší. Díky tomu mohou uživatelé zůstat ověření, aniž by se museli znovu ručně přihlašovat.

Zde je několik osvědčených postupů a doporučení, jak tokeny správně používat:

Vygenerování nového tokenu při prvním přihlášení: Při prvním přihlášení uživatele do aplikace proveďte volání koncového bodu k vytvoření nového přístupového tokenu. Tento token používejte pro všechna následující volání.
Bezpečné uložení tokenů: Přístupový token i obnovovací token byste měli bezpečně uložit na straně klienta. Může to být v paměti, v místním úložišti nebo v zabezpečených souborech cookie, v závislosti na požadavcích a hrozbách, kterým vaše aplikace čelí.
Obnovení tokenu před vypršením platnosti: Nemusíte přesně sledovat, jak dlouho byl token používán. Můžete si ponechat určitou rezervu. Platnost přístupového tokenu Boldem vyprší za 60 minut, můžete jej obnovovat třeba každých 50 minut. Tímto způsobem nehrozí, že by přístupový token vypršel v polovině požadavku.
Použití obnovovacího tokenu k vygenerování nového tokenu přístupu: Pokud platnost tokenu přístupu vyprší, použijte obnovovací token k vygenerování nového přístupového tokenu. Tento proces je pro uživatele transparentní, takže se nemusí znovu ručně přihlašovat.
Ošetření případného selhání při generování obnovovacího tokenu: Pokud se vám nepodaří vygenerovat nový přístupový token pomocí obnovovacího tokenu (platnost obnovovacího tokenu vypršela nebo byl zrušen), měli byste uživatele přesměrovat na přihlašovací stránku pro opětovné ověření.
Zneplatnění starého obnovovacího tokenu po použití: V rámci dodatečného zabezpečení můžete zneplatnit staré obnovovací tokeny, jakmile byly použity k vygenerování nového tokenu. To znamená, že pokud by se útočník dostal k obnovovacímu tokenu, může jej použít pouze jednou a legitimní uživatel si toho brzy všimne po odhlášení
Pravidelné vyměňování obnovovacích tokenů: Další doporučovanou praxí je pravidelné vyměňování obnovovacích tokenů, abyste zamezili potenciálním škodám v případě jeho kompromitace.

Uvedené postupy zajišťují rovnováhu mezi pohodlím uživatelů, kteří se díky tomu nemusí tak často přihlašovat, a bezpečností.

Vytvoření přístupového tokenu

Abyste mohli volat jednotlivé koncové body rozhraní API, je zapotřebí nejprve pomocí klíče API vygenerovat přístupový token (access_token). Přístupový token má platnost 60 minut, poté je zapotřebí jej obnovit.

Chcete-li rozhraní Boldem API efektivně otestovat, doporučujeme využít některý z nástrojů, jako je Postman, Insomnia, nebo třeba httpiness. Do těchto nástrojů můžete importovat všechny koncové body z https://api.boldem.cz/ a snadno je otestovat před jejich nasazením do vlastní aplikace.

O přístupový token požádáte zavoláním koncového bodu /v1/oauth pomocí metody POST. Příklady volání najdete níže.

Hodnoty v parametrech client_id a client_secret nahraďte hodnotami zkopírovanými z vašeho účtu Boldem.

Příklad vytvoření přístupového tokenu (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"))

Příklad vytvoření přístupového tokenu (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();

Příklad vytvoření přístupového tokenu (PHP)

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.boldem.cz/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;
?>

Vytvoření přístupového tokenu – výsledek volání

Po zavolání výše uvedeného koncového bodu byste měli v kladném případě obdržet výstup ve formátu JSON obsahující přístupový token (access_token) a obnovovací token (refresh_token):

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

Obnovení přístupového tokenu

Jelikož přístupový token má platnost 60 minut, je zapotřebí ho včas obnovit. K obnovení použijete koncový bod /v1/oauth/refresh. Příklady volání naleznete níže.

Hodnoty v parametrech access_token a refresh_token nahraďte hodnotami zkopírovanými z výsledku volání, který jste obdrželi při generování nového přístupového tokenu.

Příklad obnovení přístupového tokenu (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"))

Příklad obnovení přístupového tokenu (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();

Příklad obnovení přístupového tokenu (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;

Obnovení přístupového tokenu – výsledek volání

Po zavolání výše uvedeného koncového bodu byste měli v kladném případě obdržet výstup ve formátu JSON obsahující nový přístupový token (access_token) a obnovovací token (refresh_token):

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

Zneplatnění konkrétního obnovovacího tokenu

Chcete-li zrušit platnost určitého obnovovacího tokenu, zavolejte koncový bod /v1/oauth/revoke. Příklady volání naleznete níže.

Hodnoty v parametrech access_token a refresh_token nahraďte hodnotami zkopírovanými z výsledku volání, který jste obdrželi při generování těchto tokenů.

Příklad zneplatnění konkrétního obnovovacího tokenu (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();

Příklad zneplatnění konkrétního obnovovacího tokenu (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"))

Příklad zneplatnění konkrétního obnovovacího tokenu (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;
?>

Zneplatnění konkrétního obnovovacího tokenu – výsledek volání

Po zavolání výše uvedeného koncového bodu byste měli v kladném případě obdržet návratový kód 204 bez obsahu.

Odhlášení a zneplatnění všech obnovovacích tokenů

Chcete-li uživatele odhlásit a zrušit všechny obnovovací tokeny, zavolejte koncový bod /v1/oauth/signout bez dalších parametrů.