# auth.md — Agent-Zugang zu OGRECORDS™

OGRECORDS™ ist eine unabhängige Vertriebs- und Marketing-Plattform für
selbstveröffentlichende Artists und kleine Labels, betrieben von der
OnlineBuilders LLC. Dieses Dokument beschreibt, wie ein autonomer Agent ein
Zugangsmittel für unsere Maschinen-Schnittstellen bekommt und benutzt.

English version: <https://www.og-records.com/auth.md>

## Für wen das gilt

Für Agenten, die **im Auftrag eines bestehenden OGRECORDS-Kontos** handeln —
eines Artists oder Labels, das bereits über uns vertreibt. Jeder Schlüssel
gehört einem menschlichen Konto und erbt dessen Datengrenze: ein Agent sieht
den Katalog dieses Kontos und sonst nichts.

Es gibt keine anonyme Agent-Identität, und nichts hier legt ein Konto an. Die
OAuth-Client-Registrierung ist offen, aber ein Client ist nur ein Name und eine
Rückleitungsadresse — er liest nichts, bevor ein Kontoinhaber zustimmt.

## Zwei Wege zur Anmeldung

1. **OAuth 2.1** — für MCP-Clients wie Claude, ChatGPT oder Claude Code. Der
   Kontoinhaber meldet sich auf unserer Zustimmungsseite an; kein Schlüssel
   wird kopiert.
2. **API-Key** — für Skripte und Server-Integrationen gegen die REST-API.

Beide ergeben einen Bearer-Nachweis, den jede Schnittstelle annimmt — mit
denselben Scopes, demselben Kontingent und demselben Nutzungs-Log.

## OAuth 2.1 (Connectoren)

Wir sind selbst Authorization-Server. Discovery:

- Geschützte Ressource (RFC 9728):
  <https://www.og-records.com/.well-known/oauth-protected-resource/api/agent/mcp>
- Authorization-Server (RFC 8414):
  <https://www.og-records.com/.well-known/oauth-authorization-server>

Ein Aufruf des MCP-Endpunkts ohne Anmeldung antwortet `401` mit
`WWW-Authenticate: Bearer resource_metadata="…"` — mehr braucht ein
standardkonformer MCP-Client nicht, um den Ablauf selbst zu starten.

| Schritt | Endpunkt |
|---|---|
| Dynamic Client Registration (RFC 7591) | `POST https://api.og-records.com/api/v1/oauth/register` |
| Autorisierung (Zustimmungsseite) | `https://www.og-records.com/oauth/authorize` |
| Token | `POST https://api.og-records.com/api/v1/oauth/token` |
| Widerruf (RFC 7009) | `POST https://api.og-records.com/api/v1/oauth/revoke` |

Regeln:

- Nur Authorization-Code-Flow, **PKCE mit S256 ist Pflicht**.
- Redirect-URIs müssen `https` sein, oder `http` auf `localhost` /
  `127.0.0.1` (der Port eines Loopback-Redirects darf sich ändern).
- Öffentliche Clients (`token_endpoint_auth_method: none`) und vertrauliche
  (`client_secret_post` / `client_secret_basic`) werden unterstützt.
- Über OAuth gibt es nur **Lese**-Scopes: `read:releases`, `read:stats`,
  `read:artists`, `read:smartlinks`, `read:earnings`. Der Nutzer kann jeden
  davon abwählen. Ohne `scope` werden alle angefragt.
- Zugriffstoken (`ogr_oat_…`) gelten 1 Stunde. Refresh-Token (`ogr_ort_…`)
  gelten 60 Tage und rotieren bei jeder Nutzung — wer ein verbrauchtes
  Refresh-Token vorzeigt, beendet die Verbindung.
- `resource` muss, wenn gesendet, `https://www.og-records.com/api/agent/mcp`
  sein.
- Der Kontoinhaber sieht und trennt jede App unter
  <https://www.og-records.com/dashboard/settings/connected-apps>.

In Claude oder ChatGPT einen eigenen Connector mit der Adresse
`https://www.og-records.com/api/agent/mcp` hinzufügen und bei der Abfrage
anmelden.

## API-Keys (Skripte und Integrationen)

Das Anlegen ist ein menschlicher Schritt: ein Schlüssel öffnet einen echten
Katalog und echte Umsatzzahlen.

1. Der Kontoinhaber meldet sich unter <https://www.og-records.com/login> an.
2. API-Keys sind Early-Access-gated. Zeigt das Dashboard statt des
   Schlüssel-Formulars das Early-Access-Panel, kann der Zugang unter
   <mailto:support@og-records.com> angefragt werden — ein Mensch schaltet frei.
3. Unter <https://www.og-records.com/dashboard/settings/api-keys> wird der
   Schlüssel mit Scopes und Tier erzeugt. **Das Secret erscheint genau
   einmal**; gespeichert wird nur ein HMAC-SHA256-Digest. Verlorene Schlüssel
   werden rotiert, nicht wiederhergestellt.

Format: `ogr_pk_<env>_<16 Hex>.<Secret>`, zum Beispiel
`ogr_pk_live_a1b2c3d4e5f60718.<Secret>`. Der Teil vor dem Punkt ist ein
öffentliches Präfix, das den Schlüssel im Dashboard und im Nutzungs-Log
identifiziert; danach folgt das Geheimnis.

## Verwendung

Zugriffstoken und Schlüssel gehen in beiden Header-Formen, auf allen
Schnittstellen:

```http
Authorization: Bearer ogr_pk_live_a1b2c3d4e5f60718.<Secret>
```

```http
X-API-Key: ogr_pk_live_a1b2c3d4e5f60718.<Secret>
```

Zuerst den Schlüssel prüfen. Dieser Endpunkt verlangt keinen Scope,
funktioniert also mit jedem gültigen Schlüssel und sagt, was er darf:

```http
GET https://api.og-records.com/api/v1/public/whoami
Authorization: Bearer <Key>

200 OK
{"authenticated":true,"scopes":["read:releases","read:stats"],
 "tier":"free","rate_limit_per_day":1000}
```

## Maschinen-Schnittstellen

| Schnittstelle | Endpunkt | Hinweise |
|---|---|---|
| REST | `https://api.og-records.com/api/v1/public` | OpenAPI: <https://www.og-records.com/api-docs/openapi.json> · Doku: <https://www.og-records.com/api-docs> |
| MCP (Streamable HTTP) | `https://www.og-records.com/api/agent/mcp` | JSON-RPC 2.0, `initialize` / `tools/list` / `tools/call` |
| A2A (JSON-RPC) | `https://www.og-records.com/api/agent/a2a` | Agent-Card: <https://www.og-records.com/.well-known/agent-card.json> |
| Ausgehende Webhooks | pro Konto konfiguriert | HMAC-SHA256-signiert; `release.delivered`, `release.live`, `release.rejected`, `release.takedown` |

Die MCP- und A2A-Endpunkte sind **nur lesend**. Schreibzugriffe (Release-
Entwürfe, Smartlinks, Track-Metadaten) gibt es ausschließlich auf der
REST-API und nur mit dem passenden `write:`-Scope.

## Scopes

`read:releases`, `read:smartlinks`, `read:stats`, `read:artists`,
`read:earnings`, `write:smartlinks`, `write:releases`, `write:tracks`.

Zwei Endpunkte verlangen bewusst keinen Scope: `whoami` (ein Schlüssel muss
seine eigenen Rechte erfahren können) und `/api/v1/public/help` — dieselbe
Produktdokumentation, die jeder eingeloggte Nutzer liest.

Vertriebs-Auslöser — Submit, Resubmit, Takedown, Archivieren — sind **keinem**
Schlüssel zugänglich, in keinem Scope. Sie bewegen echte Musik in echte Stores
und bleiben hinter einer menschlichen Handlung im Dashboard.

## Kontingent und Fehler

Jede Antwort trägt `X-RateLimit-Limit`, `X-RateLimit-Remaining` und
`X-RateLimit-Reset` (Unix-Sekunden). Tageskontingent: 1.000 Anfragen im
Free-Tier, 100.000 im Business-Tier (auf Anfrage vom Team vergeben).

| Status | Bedeutung | Was der Agent tun soll |
|---|---|---|
| 401 | Nachweis fehlt, ist abgelaufen, ungültig oder widerrufen | OAuth: Zugriffstoken erneuern, scheitert das, den Ablauf neu starten. API-Key: abbrechen, ein neuer muss vom Kontoinhaber kommen. |
| 403 | Nachweis gültig, Scope fehlt | Abbrechen. Die Meldung nennt den fehlenden Scope; der Inhaber muss ihn freigeben (neu verbinden oder Schlüssel damit erzeugen). |
| 429 | Tageskontingent erschöpft | `Retry-After` (Sekunden) beachten. Der Zähler springt bei `X-RateLimit-Reset` zurück. |

## Bot-Identität

Anfragen, die OGRECORDS selbst nach außen schickt (Webhook-Zustellung,
Remote-Import von Dateien), sind nach Web Bot Auth signiert (RFC 9421,
`tag="web-bot-auth"`). Unsere öffentlichen Schlüssel:
<https://www.og-records.com/.well-known/http-message-signatures-directory>

## Weitere Discovery

- API-Katalog: <https://www.og-records.com/.well-known/api-catalog>
- Agent-Skills: <https://www.og-records.com/.well-known/agent-skills/index.json>
- Seiten-Index für LLMs: <https://www.og-records.com/llms.txt>
- Jede öffentliche Seite beantwortet außerdem `Accept: text/markdown` mit
  einer Markdown-Fassung ihrer selbst.

## Kontakt

<mailto:support@og-records.com> · Sicherheit: <https://www.og-records.com/.well-known/security.txt>