Schnellstart

Von null zum ersten erfolgreichen Aufruf.

1. Get credentials

Anbindungs-Clients werden von uns registriert, nicht im Selbstbedienungsverfahren. Schreib an support@shiftavo.com und nenn:

• für welches Unternehmen die Anbindung ist,

• was sie können muss — wir erteilen nur die Scopes, die das abdeckt (siehe Scopes).

Du bekommst drei Dinge zurück:

client_id	z. B. cust-acme-integration
client_secret	einmal angezeigt, bei uns gehasht gespeichert — nicht wiederherstellbar, sichere es also sofort
Scopes	z. B. shifts.read timesheets.read

Ein Satz Zugangsdaten gehört zu genau einem Unternehmen und erreicht kein anderes, selbst wenn du mehreren angehörst.

2. Get an access token

POST an den Token-Endpunkt des Identitätsanbieters. Die Zugangsdaten stehen im Formular-Body:

curl -X POST https://auth.shiftavo.com/identity/o/api/token \
  -d grant_type=client_credentials \
  -d client_id=cust-acme-integration \
  -d client_secret=$CLIENT_SECRET \
  -d scope=shifts.read

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "shifts.read"
}

Wichtig

Speichere das Token zwischen und verwende es bis kurz vor seinem Ablauf. Das ist eine Anforderung, keine Optimierung — ruf den Token-Endpunkt nicht einmal pro Anfrage auf.

3. Find out which host to call

Das Zugriffstoken ist ein JWT mit einem Claim api_base, der den Shard deines Unternehmens nennt:

{ "api_base": "https://app.shiftavo.com", "tenant_id": "0194d1c0-…", "…": "…" }

Lies den Host aus dem Token, statt ihn fest zu verdrahten — das erlaubt uns, Shards hinzuzufügen oder zu verschieben, ohne dass du etwas änderst. Dekodier die Nutzlast nur als Routing-Hinweis; dein eigenes Token musst du nicht prüfen.

4. Make a call

curl "$API_BASE/api/public/v1/locations/?page_size=100" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "object": "list",
  "data": [
    { "object": "location", "id": "0194d1c0-…", "name": "Bar — Hamptons" }
  ],
  "has_more": false,
  "next": null
}

Kommen deine eigenen Standorte zurück, stimmen Zugangsdaten, Scopes und Unternehmensbindung.

Dasselbe in Python

import requests

AUTH = "https://auth.shiftavo.com"

token = requests.post(
    f"{AUTH}/identity/o/api/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": "shifts.read",
    },
    timeout=30,
).json()

# `api_base` is a routing hint from the token — decode, don't verify.
import base64, json
payload = token["access_token"].split(".")[1]
api_base = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))["api_base"]

shifts = requests.get(
    f"{api_base}/api/public/v1/shifts/",
    headers={"Authorization": f"Bearer {token['access_token']}"},
    timeout=30,
).json()

Weiter

• Authentifizierung — der Token-Ablauf in voller Länge, samt Ablaufzeit und Umgang mit 401.

• Konventionen — Paginierung, Fehler, Idempotenz. Lies das, bevor du einen Client schreibst.

• API-Referenz — jeder Endpunkt.