Authenticatie
Maak een OAuth2-client aan, haal een access token op en beheer je clients.
De Tibata API gebruikt de OAuth2 client credentials flow: je service wisselt een client ID en secret in voor een access token, zonder tussenkomst van een gebruiker. Maak voor elke integrerende service een eigen client aan.
Voordat je begint
- Je hebt de rol Eigenaar of Beheerder in de organisatie. Andere leden zien API instellingen niet in het gebruikersmenu.
- Een client hoort bij één organisatie. Heb je toegang tot meerdere organisaties, open dan eerst de juiste organisatie in Tibata.
Client aanmaken
API instellingen openen
Open in Tibata het gebruikersmenu rechtsboven en kies API instellingen. De pagina toont de OAuth clients van je organisatie.
Client invullen
Klik op Nieuwe client… en vul in:
| Veld | Wat je invult |
|---|---|
| Naam | Een herkenbare naam, bijvoorbeeld die van de service die de client gebruikt |
| Scopes | De rechten die de service nodig heeft (zie Scopes) |
Klik op Client aanmaken.
Secret opslaan
De melding Sla je client secret op toont de Client ID en het Client secret. Kopieer beide en klik daarna op Ik heb het secret opgeslagen.
Het secret wordt maar één keer getoond. Kwijt? Maak een nieuw secret aan met Secret roteren (zie Clients beheren).
Access token ophalen
De voorbeelden lezen het client ID en secret uit omgevingsvariabelen:
export TIBATA_CLIENT_ID="<client-id>"
export TIBATA_CLIENT_SECRET="<client-secret>"Stuur een POST-verzoek naar het token-endpoint, met de client credentials als formuliervelden in de body:
curl -X POST https://auth.tibata.ai/api/auth/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
--data-urlencode "client_id=$TIBATA_CLIENT_ID" \
--data-urlencode "client_secret=$TIBATA_CLIENT_SECRET" \
-d "scope=spaces.read" \
-d "resource=https://api.tibata.ai/"| Veld | Waarde |
|---|---|
grant_type | Altijd client_credentials |
client_id, client_secret | De credentials van je client |
scope | De scopes die je nodig hebt, gescheiden door spaties |
resource | Altijd https://api.tibata.ai/ |
Het antwoord:
{
"access_token": "eyJhbGci...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "spaces.read"
}Het token is expires_in seconden geldig, dus één uur. Er is geen refresh token: vraag na afloop een nieuw token aan.
Het token-endpoint en de overige OAuth2-metadata staan ook in het discovery-document op https://auth.tibata.ai/.well-known/oauth-authorization-server.
API aanroepen
Zet het access token in een omgevingsvariabele:
export TIBATA_TOKEN="<access-token>"Stuur het daarna mee in de Authorization-header van elk verzoek:
curl https://api.tibata.ai/v1/spaces \
-H "Authorization: Bearer $TIBATA_TOKEN"Token vernieuwen
Een token is een uur geldig. Gebruik het voor elk verzoek in dat uur en haal kort voordat het verloopt met hetzelfde verzoek een nieuw token op. De voorbeelden vernieuwen een minuut eerder, zodat geen verzoek vertrekt met een token dat onderweg verloopt:
# Requires jq.
# Fetches a token only when there is none or it is about to expire.
tibata_token() {
now=$(date +%s)
if [ -z "$TIBATA_TOKEN" ] || [ "$now" -ge "${TIBATA_TOKEN_EXPIRES:-0}" ]; then
response=$(curl -s -X POST https://auth.tibata.ai/api/auth/oauth2/token \
-d "grant_type=client_credentials" \
--data-urlencode "client_id=$TIBATA_CLIENT_ID" \
--data-urlencode "client_secret=$TIBATA_CLIENT_SECRET" \
-d "scope=spaces.read" \
-d "resource=https://api.tibata.ai/")
expires_in=$(echo "$response" | jq -r .expires_in)
TIBATA_TOKEN=$(echo "$response" | jq -r .access_token)
TIBATA_TOKEN_EXPIRES=$(( now + expires_in - 60 ))
fi
}
tibata_token
curl https://api.tibata.ai/v1/spaces \
-H "Authorization: Bearer $TIBATA_TOKEN"Scopes
| Scope | Geeft toegang tot |
|---|---|
spaces.read | GET /v1/spaces, GET /v1/spaces/{space_id} |
spaces.write | POST /v1/spaces, POST /v1/spaces/batch, PATCH /v1/spaces/{space_id} |
spaces.delete | DELETE /v1/spaces/{space_id} |
integrations.read | GET /v1/integrations/connections, GET /v1/integrations/connections/{connection_id}/mappings |
integrations.write | PUT /v1/integrations/connections/{connection_id}/mappings |
Geef een client alleen de scopes die de service echt gebruikt.
Clients beheren
Elke client heeft in het overzicht op API instellingen een rij met deze acties:
| Actie | Wat er gebeurt |
|---|---|
| Scopes bewerken… | Je wijzigt de scopes van de client. |
| Secret roteren | De client krijgt een nieuw secret, dat eenmalig in de melding Sla je client secret op verschijnt. |
| Client uitschakelen | API-aanroepen met tokens van deze client worden direct geweigerd. Client inschakelen zet de client weer aan. |
| Client verwijderen | De client wordt direct verwijderd, zonder bevestiging. |
Na rotatie is het oude secret onmiddellijk ongeldig. Werk het secret in je service direct na het roteren bij.
Aanbevelingen
- Gebruik één client per service. Dan kun je één service uitschakelen of roteren zonder de rest te raken.
- Bewaar het client ID en secret in een secret manager of in omgevingsvariabelen, nooit in broncode.
- Gebruik het token opnieuw en vraag automatisch een nieuw token aan voordat het verloopt (zie Token vernieuwen).
- Geef de client alleen de scopes die hij nodig heeft.