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

# Agent registrieren

> Registrieren Sie eine neue Maschinenagentenidentität mit kryptografischem Schlüsselpaar und bereichsbezogenen Berechtigungen

# Agent registrieren

`POST /v1/agents`

Registriert eine neue Maschinenagentenidentität für den authentifizierten Mandanten. Die Plattform generiert ein Ed25519-Schlüsselpaar für den Agenten, weist eine MAIP-konforme Agenten-ID zu und zeichnet den ursprünglichen Schlüssel im Schlüsselhistorien-Ledger auf. Neu registrierte Agenten beginnen mit dem Status `active` und einem anfänglichen Vertrauenswert von `0.500`.

> [!NOTE]
>
> Die Anzahl der Agenten, die Sie registrieren können, hängt von Ihrem Abrechnungsplan ab. Wenn Sie
> Ihr Planlimit überschreiten, gibt die API `402 Payment Required` zurück. Kontaktieren Sie den Vertrieb
> für Agentenlimits der Enterprise-Stufe.

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

**id** `string`

Interner UUID-Primärschlüssel.

**agent\_id** `string`

MAIP-konformer Agentenbezeichner im Format `maip:<tenant8>:<ulid>`. Verwenden Sie diesen Wert
in allen nachfolgenden API-Aufrufen, die diesen Agenten referenzieren.

**tenant\_id** `string`

UUID des besitzenden Mandanten.

**agent\_type** `string`

Der registrierte Agententyp.

**display\_name** `string`

Menschenlesbarer Agentenname.

**description** `string`

Agentenbeschreibung, falls vorhanden.

**trust\_level** `string`

Anfängliches Vertrauensniveau. Neu registrierte Agenten beginnen bei `"authenticated"`.

**trust\_score** `number`

Numerischer Vertrauenswert (0,0 bis 1,0). Neu registrierte Agenten beginnen bei `0.500`.

**status** `string`

Lebenszyklusstatus des Agenten. Bei der Erstellung immer `"active"`.

**public\_key** `string`

Base64url-kodierter Ed25519-Public-Key, der für diesen Agenten generiert wurde. Speichern Sie diesen
sicher zur Signaturprüfung.

**key\_id** `string`

Eindeutiger Identifikator für den Signierschlüssel des Agenten. Referenziert in Belegen und
Bestätigungen.

**scopes** `string[]`

Die dem Agenten zugewiesenen effektiven Scopes.

**metadata** `object`

Das Metadatenobjekt, falls vorhanden.

**delegation\_depth** `number`

Aktuelle Tiefe der Delegationskette. Immer `0` für direkt registrierte Agenten.
Maximale Tiefe ist `8` pro MAIP-Protokoll.

**created\_by\_user\_id** `string`

UUID des Benutzers, der den Agenten registriert hat, falls über Benutzer-Token authentifiziert.

**expires\_at** `string`

Ablaufzeitstempel, falls festgelegt.

**created\_at** `string`

ISO 8601 Erstellungszeitstempel.

**updated\_at** `string`

ISO 8601 Zeitstempel der letzten Aktualisierung.

### Beispiel

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agents \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "llm",
    "display_name": "Customer Support Bot",
    "description": "Handles Tier-1 customer support inquiries via chat",
    "scopes": ["data:read", "tool:search.web", "!data:delete"],
    "metadata": {
      "team": "support",
      "model": "claude-3.5-sonnet",
      "environment": "production"
    }
  }'
```


## OpenAPI

````yaml de/mint-openapi.yaml POST /v1/agents
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/agents:
    post:
      tags:
        - Machine Identity
      summary: Agent registrieren
      description: >-
        Registrieren Sie eine neue Maschinenagentenidentität. Gibt den
        Agenten-Datensatz zurück, einschließlich eines generierten öffentlichen
        Schlüssels und eines anfänglichen Vertrauenswürdigkeitswerts.
      operationId: maip.agents.register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                agent_type:
                  type: string
                  description: Klassifizierung des Agenten
                  enum:
                    - orchestrator
                    - worker
                    - inference
                    - pipeline
                    - service
                    - bot
                    - llm
                description:
                  type: string
                  description: Freitextbeschreibung des Agentenzwecks
                display_name:
                  type: string
                  description: Menschenlesbarer Agentenname
                  maxLength: 256
                expires_at:
                  format: date-time
                  nullable: true
                  type: string
                metadata:
                  description: Beliebige Schlüssel-Wert-Metadaten
                scopes:
                  items:
                    type: string
                  type: array
                  description: Dem Agenten gewährte Berechtigungsumfänge
              type: object
              required:
                - display_name
      responses:
        '201':
          description: Agent registriert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaipAgent'
        '400':
          description: Validierungsfehler
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Authentifizierung erforderlich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Ratenlimit überschritten
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - APIKey: []
components:
  schemas:
    MaipAgent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        agent_type:
          type: string
          enum:
            - orchestrator
            - worker
            - inference
            - pipeline
            - service
            - bot
            - llm
        display_name:
          type: string
          maxLength: 256
        description:
          type: string
        status:
          type: string
          enum:
            - active
            - suspended
            - revoked
        scopes:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        trust_score:
          type: number
          format: float
          minimum: 0
          maximum: 1
        public_key:
          type: string
          description: Base64-kodierter öffentlicher Schlüssel
        session_count:
          type: integer
        keys:
          type: array
          items:
            type: object
            properties:
              kid:
                type: string
              algorithm:
                type: string
              public_key:
                type: string
              status:
                type: string
                enum:
                  - active
                  - disabled
                  - expired
        created_at:
          type: string
          format: date-time
        updated_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.