Naar inhoud springen
Tibata
Docs

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:

VeldWat je invult
NaamEen herkenbare naam, bijvoorbeeld die van de service die de client gebruikt
ScopesDe 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/"
VeldWaarde
grant_typeAltijd client_credentials
client_id, client_secretDe credentials van je client
scopeDe scopes die je nodig hebt, gescheiden door spaties
resourceAltijd 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

ScopeGeeft toegang tot
spaces.readGET /v1/spaces, GET /v1/spaces/{space_id}
spaces.writePOST /v1/spaces, POST /v1/spaces/batch, PATCH /v1/spaces/{space_id}
spaces.deleteDELETE /v1/spaces/{space_id}
integrations.readGET /v1/integrations/connections, GET /v1/integrations/connections/{connection_id}/mappings
integrations.writePUT /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:

ActieWat er gebeurt
Scopes bewerken…Je wijzigt de scopes van de client.
Secret roterenDe client krijgt een nieuw secret, dat eenmalig in de melding Sla je client secret op verschijnt.
Client uitschakelenAPI-aanroepen met tokens van deze client worden direct geweigerd. Client inschakelen zet de client weer aan.
Client verwijderenDe 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.

Op deze pagina