Agent-Authentifizierung (agentische Registrierung)

Uptimeify betreibt unter https://uptimeify.io einen agentischen Registrierungs- Autorisierungsserver im WorkOS-Stil. Agenten registrieren sich, tauschen eine dienstsignierte Identitäts-Assertion gegen ein kurzlebiges, opakes Zugriffstoken und rufen die nur lesende API auf. Alle Endpunkte unten werden ausschließlich auf dem kanonischen Host uptimeify.io bereitgestellt (auf Custom-Domains liefern sie 404).

Entdecken

curl https://uptimeify.io/.well-known/oauth-authorization-server
curl https://uptimeify.io/.well-known/oauth-protected-resource

Die Metadaten des Autorisierungsservers folgen RFC 8414 (token_endpoint, revocation_endpoint, jwks_uri, grant_types_supported, scopes_supported) und ergänzen einen agent_auth-Erweiterungsblock mit identity_endpoint, claim_endpoint, identity_types_supported (derzeit ["anonymous", "service_auth"]) und einem skill-Verweis auf /auth.md. Die Protected-Resource-Metadaten folgen RFC 9728.

Registrieren (anonym)

curl -X POST https://uptimeify.io/agent/identity \
  -H 'Content-Type: application/json' \
  -d '{"type":"anonymous"}'

{
  "registration_id": "reg_…",
  "identity_assertion": "<jwt>",
  "pre_claim_scopes": ["tools.public"],
  "post_claim_scopes": ["api.read"],
  "token_endpoint": "https://uptimeify.io/oauth2/token"
}

Die identity_assertion ist ein EdDSA-JWT mit rund 24 Stunden Gültigkeit: dein langlebiges Berechtigungsmerkmal. Rate-Limit: 30 Anfragen/Minute pro Aufrufer.

post_claim_scopes beschreibt den Scope, den eine geclaimte Registrierung erreicht (api.read). Eine anonyme Registrierung ist sofort aktiv mit tools.public und direkt nutzbar: das Claimen ist optional. Die Antwort enthält außerdem ein einmal verwendbares claim_token (clm_…) und eine claim_url: Willst du diese Registrierung auf api.read hochstufen, findest du im Claim-Flow, wie du es einlöst.

Registrieren (service_auth)

Die service_auth-Registrierung ist ausschließlich claimbar: Sie startet als pending und erzeugt kein Token, bis ein angemeldeter Nutzer sie autorisiert hat. Im Claim-Flow findest du den vollständigen Request POST /agent/identity {"type":"service_auth", "login_hint":"…"}, den menschlichen Zustimmungsschritt und wie du /oauth2/token auf das resultierende api.read-Zugriffstoken pollst.

Gegen ein Zugriffstoken tauschen

curl -X POST https://uptimeify.io/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
  --data-urlencode 'assertion=<identity_assertion>'

{ "access_token": "wsma_…", "token_type": "Bearer", "expires_in": 3600, "scope": "tools.public" }

Das Zugriffstoken ist opak, läuft nach 1 Stunde (3600s) ab und muss danach erneut aus der Identitäts-Assertion erzeugt werden. Rate-Limit: 60 Anfragen/Minute pro Aufrufer.

Verwenden (nur lesend)

curl https://uptimeify.io/api/tools/dns-lookup?domain=deinkunde.com \
  -H 'Authorization: Bearer wsma_…'

Agent-Tokens sind nur lesend. Der anonyme Scope tools.public erreicht ausschließlich die öffentlichen Prüf-Tools (GET /api/tools/*). Ein geclaimtes Token mit Scope api.read (siehe Claim-Flow) erreicht zusätzlich GET /api/websites*, GET /api/incidents* und GET /api/health, begrenzt auf die Organisation (bzw. den einzelnen Kunden) des autorisierenden Nutzers. Jeder Schreibzugriff oder jede GET/HEAD-Anfrage außerhalb der zum Scope passenden Allowlist liefert 403 mit data.code = agentTokenReadOnly.

Widerrufen

curl -X POST https://uptimeify.io/oauth2/revoke \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=wsma_…' \
  --data-urlencode 'token_type_hint=access_token'

Idempotentes 200: gelingt immer, auch bei einem unbekannten oder bereits widerrufenen Token.

Häufige Fehler

anonymous und service_auth sind beide aktiviert. Die service_auth-Registrierung und die Claim-Zeremonie haben eigene Fehlercodes: siehe Claim-Flow und die Fehlercode-Referenz. identity_assertion (ID-JAG, mit der eine bereits vertraute externe OIDC-Identität direkt ein Token erzeugen kann) ist noch nicht verfügbar.