Ověřování požadavků na API

Na této stránce se dozvíte, jak ověřovat požadavky, abyste získali přístup k prostředkům na účtech Dronetag.

Nabízíme dva způsoby ověřování: osobní přístupové tokeny (Personal Access Tokens, PAT) a OpenID Connect. Každý se hodí pro jiné použití, proto si přečtěte, který lépe odpovídá vašemu projektu.

Osobní přístupové tokeny (Personal Access Tokens, PAT)

Pokud chcete pracovat s vlastními daty ze svého účtu Dronetag — například je dodatečně zpracovávat, vytvořit si vlastní nástroj pro příkazovou řádku (CLI) nebo data převádět do jiného softwaru —, nabízíme pro jednoduchý a přímý přístup k API osobní přístupové tokeny (PAT).

Tyto tokeny jsou snadno použitelné, ale méně bezpečné. Pro robustnější integrace určené veřejnosti doporučujeme spíše OpenID Connect.

Bezpečnost

Osobní přístupové tokeny dávají plný přístup k prostředkům vašeho účtu. Uchovávejte je bezpečně a dejte pozor, abyste je omylem nikomu nezpřístupnili (například zveřejněním na internetu).
Z bezpečnostních důvodů platí PAT nejvýše 90 dní.

Experimentální funkce

Osobní přístupové tokeny jsou zatím ve fázi experimentu. Pokud při jejich používání narazíte na problém, dejte nám vědět.

Vytvoření nového tokenu

• Vytvoření v naší aplikaci
• Vytvoření přes API

1. Přihlaste se ke svému účtu Dronetag v aplikaci Dronetag.
2. Přejděte na obrazovku Profile.
3. Přejděte na obrazovku Account, kde uvidíte podrobnosti o účtu.
4. Otevřete obrazovku Personal Access Tokens.

Zde vytvoříte nový token tlačítkem Create token.

Pokud potřebujete osobní přístupový token vytvořit programově, pošlete požadavek POST na endpoint /v2/pats/tokens. Takový požadavek ale musíte navíc ověřit přístupovým tokenem získaným přes OpenID Connect.

Požadavek musí obsahovat heslo k vašemu účtu. Heslo se neukládá, slouží jen k autorizaci vydání tokenu.

post/v2/pats/tokens dokumentace API »

{
    "password": "hunter2",
    "expires_at": "2025-09-09"
}

Nově vydaný osobní přístupový token si bezpečně uložte. Znovu ho už zobrazit nepůjde.

Autorizace požadavků tokenem

Token nyní můžete při požadavcích posílat v HTTP hlavičce X-Personal-Access-Token.

Omezení: podporovány jsou jen HTTP požadavky

Osobní přístupové tokeny lze použít jen pro HTTP požadavky. Websockety pomocí PAT ověřit nelze.

Příklad požadavku s PAT

POST /v2/airspace/telemetry/ua HTTP/1.1
Host: api.dronetag.app
Accept: */*
X-Personal-Access-Token: 4c5250130bbce349.b0dc901facd944e999b32ebf984c5250130bbce349b0dc901facd944e999b32e

Implementace OpenID Connect

Když implementujete přihlášení Sign in with Dronetag, umožníte uživatelům přistupovat k jejich datům přes vaši aplikaci. Tento způsob je spolehlivější a nabízí standardizovaný přístup k ověřování.

Co je OpenID Connect (OIDC)

Naše implementace vychází z OpenID Connect (nezaměňujte s OpenID). Díky OIDC můžete využít existující knihovny a vaše aplikace ho možná už podporuje. Více se dozvíte na webu OpenID Foundation.

Abyste mohli OIDC ve své aplikaci použít, potřebujete vlastní client ID a secret. Pokud jste tyto přihlašovací údaje ještě nedostali, kontaktujte nás.

Implementace ověřování ve vaší aplikaci

• Použití hotové knihovny OIDC
• Ruční vyžádání tokenů

Doporučujeme projít certifikované implementace OpenID Connect a vybrat knihovnu, která se pro váš projekt hodí nejlépe.

Pokud to váš klient OIDC podporuje, můžete použít konfigurační JSON OpenID, který je k dispozici na adrese:

https://auth.dronetag.app/realms/dcp/.well-known/openid-configuration

Klienta OIDC můžete také nakonfigurovat ručně pomocí těchto endpointů:

Položka	URL
Authorization Endpoint	https://auth.dronetag.app/realms/dcp/protocol/openid-connect/auth
Token Endpoint	https://auth.dronetag.app/realms/dcp/protocol/openid-connect/token
User Info Endpoint	https://auth.dronetag.app/realms/dcp/protocol/openid-connect/userinfo
Client ID	Přidělen vaší aplikaci
Client Secret	Přidělen vaší aplikaci

Pokud knihovnu OIDC použít nechcete, můžete si tokeny vyžádat ručně HTTP požadavkem na adresu:

https://auth.dronetag.app/realms/dcp/protocol/openid-connect/token

V těle požadavku pošlete tyto parametry:

• grant_type: password
• client_id: vaše client ID
• client_secret: váš client secret
• username: e-mail uživatelského účtu Dronetag
• password: heslo k uživatelskému účtu Dronetag

Příklad získání přístupového tokenu přes cURL

curl -X POST "https://auth.dronetag.app/realms/dcp/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=<your-client-id>" \
-d "client_secret=<your-client-secret>" \
-d "username=<your-username>" \
-d "password=<your-password>"

Odpověď

Pokud požadavek uspěje, dostanete odpověď JSON s tímto obsahem:

{
    "access_token": "eyJhbGc...",
    "expires_in": 1200,
    "refresh_expires_in": 604800,
    "refresh_token": "eyJhbGc...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "35d764ee-c27c-4763-bc05-5ffa2e2b822e",
    "scope": "email"
}

Tabulka výše předpokládá, že vaše aplikace už má přidělené „Client ID“ a „Client Secret“. Pro testování můžete použít obecné Client ID dronetag-integration-test, ke kterému secret není potřeba. Pro produkční provoz musí mít každá aplikace vlastní jedinečné Client ID, jinak může být omezen objem stahovaných dat. Přihlašovací údaje vám vydá podpora Dronetagu.

Použití přístupových tokenů

Osobní přístupové tokeny i přístupové tokeny získané přes OIDC můžete k ověření požadavků na API posílat jako Bearer token v hlavičce Authorization.

Příklad požadavku

POST /v2/airspace/telemetry/ua HTTP/1.1
Host: api.dronetag.app
Accept: */*
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItQllNT2...

Obnovování tokenů

Přístupové tokeny vydávané jako JWT mají krátkou platnost a po vypršení je nutné je obnovit. Více o obnovovacích tokenech (refresh token) a jejich bezpečném používání najdete v těchto zdrojích (anglicky):

• What Are Refresh Tokens and How to Use Them Securely - Auth0
• Understanding Refresh Tokens, Access Tokens, and ID Tokens in OIDC Protocol - Logto
• Refresh Access Tokens and Rotate Refresh Tokens - Okta