> ## 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.

# Sitzung erstellen

> Erstellen Sie eine zeitlich begrenzte authentifizierte Sitzung für einen Maschinenagenten mit bereichsbezogenen Zugriffstoken.

# Sitzung erstellen

`POST /v1/agent-sessions`

Erstellt eine neue authentifizierte Sitzung für einen Maschinenagenten. Die Sitzung bindet ein zeitlich begrenztes Zugriffstoken und ein Aktualisierungstoken an den Agenten, mit einem expliziten Satz von Scopes, der eine Untermenge der dem Agenten gewährten Scopes sein muss.

Die `token` und `refresh_token` werden nur in der Erstellungsantwort zurückgegeben. Speichern Sie sie sicher – sie können später nicht wiederhergestellt werden.

> [!WARNING]
>
> Die Felder `token` und `refresh_token` werden in dieser
> Antwort. Speichern Sie sie in einem sicheren Secrets Manager oder verschlüsselten Speicher
> sofort. Bei Verlust die Sitzung beenden und eine neue erstellen.

### Authentifizierung

Erfordert `X-API-Key` Header oder Bearer JWT Token. Der Arbeitsbereich wird aus den authentifizierten Anmeldeinformationen abgeleitet; senden Sie `X-Tenant-ID` nicht.

### Antwort

**session** `object`

Das erstellte Sitzungsobjekt enthält:

**session.id** `string`

Interner UUID-Primärschlüssel.

**session.session\_id** `string`

MAIP-Sitzungsbezeichner im Format `maip-sess:<short-uuid>:<random-hex>`.
Verwenden Sie diese ID in nachfolgenden API-Aufrufen.

**session.agent\_id** `string`

Der Agent, zu dem diese Sitzung gehört.

**session.status** `string`

Sitzungsstatus. Bei der Erstellung immer `"active"`.

**session.scopes** `string[]`

Die effektiven Scopes für diese Sitzung.

**session.metadata** `object`

Sitzungsmetadaten.

**session.expires\_at** `string`

ISO 8601 Ablaufzeitstempel.

**session.created\_at** `string`

ISO 8601 Erstellungszeitstempel.

**session.updated\_at** `string`

ISO 8601 Zeitstempel der letzten Aktualisierung.

**token** `string`

Opaker Zugriffstoken zur Authentifizierung von API-Anfragen innerhalb dieser Sitzung.
64-stelliger Hex-String. **Nur einmal zurückgegeben.**

**refresh\_token** `string`

Token zum Aktualisieren der Sitzung vor Ablauf. 64-stelliger Hex-String.
**Wird nur einmal zurückgegeben.**

### Beispiel

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "scopes": ["data:read", "tool:search.web"],
    "ttl_minutes": 120,
    "metadata": {
      "purpose": "customer-inquiry-batch-2026-04-06",
      "orchestrator": "support-pipeline-v2"
    }
  }'
```

***

### Sitzungslebenszyklus

```
Created (active) --> Refreshed (active) --> Expired (expired)
      |                                         |
      +--> Terminated (terminated)               |
      |                                         |
      +--> Handed Off (handed_off) --> New Session (active)
```

Ein Sitzungsbeleg wird automatisch erstellt, wenn die Sitzung beginnt, und verknüpft die Sitzung mit dem Audit-Trail des Agenten.


## OpenAPI

````yaml de/mint-openapi.yaml POST /v1/agent-sessions
openapi: 3.0.3
info:
  title: Truthlocks API
  description: >
    Truthlocks ist eine universelle Verifizierungsinfrastruktur für Dokumente,
    Anmeldeinformationen und digitale Assets.

    Diese Spezifikation definiert die kanonische API für die Interaktion mit
    Truthlocks-Diensten.


    ## Basis-URLs

    - **Produktion**: `https://api.truthlocks.com`

    - **Sandbox**: `https://sandbox-api.truthlocks.com`


    ## Authentifizierung

    - **API-Schlüssel**: Verwenden Sie den Header `X-API-Key` für
    Machine-to-Machine-Operationen

    - **Bearer Tokens**: Verwenden Sie `Authorization: Bearer <jwt>` für
    benutzerinitiierte Operationen


    ## Mandantenidentität

    In der Produktion wird die Mandantenidentität aus dem authentifizierten
    Kontext (API-Schlüssel oder JWT) abgeleitet.

    Der Header `X-Tenant-ID` wird in der Produktion ignoriert, um Spoofing zu
    verhindern.
  version: 1.0.0
  contact:
    name: Truthlocks Support
    url: https://truthlocks.com/support
    email: support@truthlocks.com
servers:
  - url: https://api.truthlocks.com
    description: Produktions-API
  - url: https://sandbox-api.truthlocks.com
    description: Sandbox-Umgebung
security:
  - APIKey: []
  - BearerAuth: []
tags:
  - name: Authentication
    description: API-Schlüssel- und Token-Verwaltung
  - name: Issuers
    description: Ausstellerregistrierung und Vertrauensmanagement
  - name: Keys
    description: Kryptographische Schlüsselverwaltung für Aussteller
  - name: Attestations
    description: Bestätigungslebenszyklus (prägen, widerrufen, ersetzen)
  - name: Verification
    description: Bestätigungsverifizierung und Proof-Bundles
  - name: Governance
    description: Aussteller-Governance-Workflows (nur Admin)
  - name: Identity
    description: Organisations-, Benutzer- und Rollenverwaltung
  - name: Audit
    description: Audit-Ereignisabfragen
  - name: Tenant Console
    description: Mandantenprofil- und Lebenszyklus-Endpunkte
  - name: Health
    description: Endpunkte für Dienststatus und Bereitschaft
  - name: Risk
    description: Erfassung von Risikosignalen und Betrugserkennung
  - name: Risk Enforcement
    description: >-
      Risikodurchsetzungsmaßnahmen – Blockieren, Herausfordern, Quarantäne und
      Konfiguration
  - name: Billing
    description: Verwaltung von Abrechnung, Abonnements und Add-ons
  - name: Machine Identity
    description: >-
      Machine Agent Identity Protocol (MAIP) – Agentenregistrierung, Sitzungen,
      Vertrauen, Zeugen, Compliance, Orchestrierung und Beobachtbarkeit
externalDocs:
  description: Transparenz-API nur lesend (separate Dienstspezifikation)
  url: >-
    https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
  /v1/agent-sessions:
    post:
      tags:
        - Machine Identity
      summary: Sitzung erstellen
      description: >-
        Erstellt eine kurzlebige Sitzung für einen Agenten. Das Sitzungstoken
        wird einmal zurückgegeben und muss in nachfolgenden Anfragen innerhalb
        des TTL-Fensters verwendet werden.
      operationId: maip.sessions.create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_id:
                  type: string
                  description: Agent, für den die Sitzung erstellt werden soll
                  format: uuid
                metadata: {}
                scopes:
                  items:
                    type: string
                  type: array
                  description: >-
                    Bereiche für diese Sitzung (muss eine Untermenge der
                    Agentenbereiche sein)
                ttl_minutes:
                  type: integer
              type: object
              required:
                - agent_id
      responses:
        '201':
          description: Sitzung erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipSession'
        '400':
          description: Validierungsfehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Authentifizierung erforderlich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Agent nicht gefunden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Ratenlimit überschritten
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipSession:
      type: object
      properties:
        session_id:
          type: string
          format: uuid
        agent_id:
          type: string
          format: uuid
        token:
          type: string
          description: Sitzungs-Bearer-Token (einmalig bei Erstellung zurückgegeben)
        scopes:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - active
            - terminated
            - expired
        metadata:
          type: object
          additionalProperties: true
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        terminated_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      required:
        - code
        - message
        - http_status
      properties:
        code:
          type: string
          description: Maschinenlesbarer Fehlercode
          enum:
            - AUTH_REQUIRED
            - AUTH_INVALID
            - PERMISSION_DENIED
            - TENANT_IDENTITY_UNVERIFIED
            - NOT_FOUND
            - VALIDATION_ERROR
            - CONFLICT
            - PAYLOAD_TOO_LARGE
            - RATE_LIMIT_EXCEEDED
            - QUOTA_EXCEEDED
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
        message:
          type: string
          description: Menschenlesbare Fehlermeldung
        http_status:
          type: integer
          description: HTTP-Statuscode
        retry_after_ms:
          type: integer
          description: >-
            Millisekunden, die vor einem erneuten Versuch gewartet werden sollen
            (für Ratenbegrenzungen)
        details:
          type: object
          description: Zusätzlicher Fehlerkontext
      example:
        code: AUTH_REQUIRED
        message: Authentication required
        http_status: 401
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API-Schlüssel für die Maschine-zu-Maschine-Authentifizierung
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT für benutzerinitiierte Operationen

````

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