> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentenautorisierung

> Bereichsbasierte Autorisierung, Sitzungsverwaltung und Tool-Aufruf für KI-Agenten.

# Agenten-Autorisierung

Jeder KI-Agent in der Truthlocks-Plattform arbeitet unter einem strengen Autorisierungsmodell. Agenten müssen registriert, mit Geltungsbereichen versehen und zeitlich begrenzte Sitzungen erstellen, bevor sie Maßnahmen ergreifen können.

## Autorisierungsablauf

```
Register Agent → Assign Scopes → Create Session → Execute Actions → Terminate Session
      │               │                │                │               │
      ▼               ▼                ▼                ▼               ▼
  agent_id        scope_ids       session_token    audit_logged      cleanup
```

> [!TIP]
>
> Alle Agentenautorisierungs-Endpunkte – Scopes, Sessions und Tools – verfügen über einen interaktiven API-Playground. Öffnen Sie einen beliebigen Endpunkt in der [Agent Sessions & Tools](https://docs.truthlocks.com/de/api-reference/machine-identity/sessions/create.md) API-Referenz und klicken Sie auf **Senden**, um ihn gegen die Sandbox zu testen.

## Geltungsbereichsmodell

Bereiche folgen einem hierarchischen `resource:action` Muster. Wenn ein Agent eine Sitzung anfordert, kann er nur Bereiche anfordern, die bei der Registrierung zugewiesen wurden.

### Definieren benutzerdefinierter Bereiche

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/scopes \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "invoices:approve",
    "description": "Approve invoices up to configured threshold",
    "constraints": {
      "max_amount_cents": 500000,
      "require_dual_approval_above": 100000
    }
  }'
```

### Eingebaute Bereiche

| Umfang | Beschreibung |
| - | - |
| `agents:read` | Agenten auflisten und prüfen |
| `agents:write` | Agenten registrieren und aktualisieren |
| `receipts:write` | Belege für Mint-Aktionen |
| `attestations:read` | Attestierungsdaten lesen |
| `attestations:write` | Neue Attestierungen erstellen |
| `trust-scores:read` | Vertrauensbewertungsdaten lesen |
| `trust-scores:compute` | Neuberechnung des Vertrauens-Scores auslösen |
| `delegations:offer` | Mandantenübergreifende Delegation anbieten |
| `delegations:accept` | Delegationsangebote annehmen |
| `compliance:write` | Compliance-Prüfungen erstellen |
| `orchestrations:execute` | Multi-Agenten-Workflows ausführen |
| `datasets:attest` | Datenherkunft attestieren |
| `models:attest` | Modellherkunft attestieren |

## Sitzungsverwaltung

Sitzungen bieten zeitlich begrenzte Ausführungskontexte mit automatischem Ablauf und optionaler IP-Zulassungsliste.

### Erstellen einer Sitzung

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "scopes": ["receipts:write", "attestations:read"],
    "ttl_seconds": 3600,
    "ip_allowlist": ["10.0.0.0/8"],
    "metadata": {
      "task": "process-quarterly-invoices",
      "initiated_by": "user:alice@corp.com"
    }
  }'
```

**Antwort:**

```json theme={null}
{
  "id": "maip-session:01JYYYY",
  "agent_id": "maip-agent:01JXXXX",
  "token": "mst_live_...",
  "scopes": ["receipts:write", "attestations:read"],
  "expires_at": "2026-04-06T13:00:00Z",
  "status": "active"
}
```

### Sitzungslebenszyklus

| Status | Beschreibung |
| - | - |
| `active` | Sitzung ist gültig und akzeptiert Anfragen |
| `expired` | TTL abgelaufen – automatische Bereinigung |
| `terminated` | Explizit vom Benutzer oder System beendet |
| `suspended` | Angehalten aufgrund von Anomalieerkennung |

### Eine Sitzung beenden

```bash theme={null}
curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-session:01JYYYY \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Task completed" }'
```

## Tool-Registrierung und -Aufruf

Agenten können Tools registrieren, die sie bereitstellen, und Tools aufrufen, die von anderen Agenten registriert wurden (vorbehaltlich von Bereichsprüfungen).

### Ein Tool registrieren

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "name": "generate-invoice",
    "description": "Generate PDF invoice from order data",
    "input_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "format": { "type": "string", "enum": ["pdf", "html"] }
      },
      "required": ["order_id"]
    }
  }'
```

### Ein Tool aufrufen

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/tools/invoice-generator/invoke \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "session_id": "maip-session:01JYYYY",
    "input": { "order_id": "ord_123", "format": "pdf" }
  }'
```

Jeder Tool-Aufruf ist:

1. **Bereichsgeprüft** – die Sitzung muss den erforderlichen Bereich haben
2. **Ratenbegrenzt** – gemäß dem Kontingent für Tool-Aufrufe Ihres Plans
3. **Audit-protokolliert** – vollständige Eingabe/Ausgabe im Audit-Trail aufgezeichnet
4. **Verbrauchsabhängig** – wird auf Ihre Abrechnungsberechtigungen angerechnet

## Best Practices für die Sicherheit

> [!WARNING]
>
> Betten Sie niemals Sitzungstoken in clientseitigen Code ein. Sitzungstoken gewähren den vollen Umfang der Sitzung und sollten als Geheimnisse behandelt werden.

1. **Prinzip der geringsten Privilegien** – Fordern Sie nur die für die aktuelle Aufgabe benötigten Bereiche an
2. **Kurzlebige Sitzungen** – Verwenden Sie die kürzeste praktikable TTL (Standard: 1 Stunde)
3. **IP-Zulassungsliste** – Beschränken Sie Sitzungen auf bekannte Netzwerkbereiche
4. **Anmeldeinformationen rotieren** – Agenten-Signierschlüssel regelmäßig neu generieren
5. **Vertrauensscores überwachen** – Warnungen einrichten, wenn Vertrauensscores unter Schwellenwerte fallen
6. **Kill Switch verwenden** – Kompromittierte Agenten sofort widerrufen

## Nächste Schritte

> [card] [MAIP-Richtlinien](https://docs.truthlocks.com/guides/maip-policies.md)
>
> Laufzeit-Durchsetzungsregeln basierend auf Vertrauenswerten, Scopes und Delegationstiefe.

> [card] [Vertrauens-Scores](https://docs.truthlocks.com/guides/trust-scores.md)
>
> Kontinuierliche Verhaltensvertrauensbewertung für Agenten.

> [card] [Mandantenübergreifende Delegation](https://docs.truthlocks.com/guides/cross-tenant-delegation.md)
>
> Ermöglichen Sie Agenten, organisationsübergreifend zu agieren.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.