---
title: Agent-Authentifizierung (agentische Registrierung)
description: Registriere einen KI-Agenten und erhalte ein kurzlebiges, nur lesendes Zugriffstoken für die Uptimeify-API.
---

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

```bash
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](https://www.rfc-editor.org/rfc/rfc8414)
(`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](https://www.rfc-editor.org/rfc/rfc9728).

## Registrieren (anonym)

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

```json
{
  "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](/de/api/agent-auth/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](/de/api/agent-auth/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

```bash
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>'
```

```json
{ "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)

```bash
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](/de/api/agent-auth/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

```bash
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

| Status | `error` / `data.code` | Bedeutung |
| --- | --- | --- |
| 400 | `service_auth_not_enabled` | Der angeforderte Identitätstyp ist noch nicht aktiviert. |
| 400 | `issuer_not_enabled` | `identity_assertion` (ID-JAG) ist noch nicht aktiviert. |
| 400 | `invalid_request` | Unbekannter oder fehlender Identitätstyp bei `/agent/identity`, oder fehlende `assertion` bei `/oauth2/token`. |
| 400 | `unsupported_grant_type` | `/oauth2/token` unterstützt ausschließlich den Grant `urn:ietf:params:oauth:grant-type:jwt-bearer`. |
| 400 | `invalid_grant` | Die Assertion ist ungültig/abgelaufen, oder ihre Registrierung ist widerrufen/abgelaufen. |
| 403 | `agentTokenReadOnly` | Ein Agent-Token versuchte einen Schreibzugriff oder einen Pfad außerhalb der Allowlist. Siehe [Fehlercodes](/de/api/error-codes-and-known-pitfalls). |
| 404 | - | Auf einer Custom-Domain angefragt, oder (nur bei den Discovery-Endpunkten) die Agent-Auth-Funktion ist deaktiviert. |
| 503 | - | `/agent/identity` oder `/oauth2/token` wurde aufgerufen, während die Agent-Auth-Funktion deaktiviert ist (kein Signaturschlüssel konfiguriert). |
| 429 | - | Rate-Limit bei `/agent/identity`, `/oauth2/token` oder `/oauth2/revoke` überschritten. |

`anonymous` und `service_auth` sind beide aktiviert. Die `service_auth`-Registrierung und die
Claim-Zeremonie haben eigene Fehlercodes: siehe [Claim-Flow](/de/api/agent-auth/claim-flow)
und die [Fehlercode-Referenz](/de/api/error-codes-and-known-pitfalls). `identity_assertion`
(ID-JAG, mit der eine bereits vertraute externe OIDC-Identität direkt ein Token erzeugen
kann) ist noch nicht verfügbar.