REST-API

Adresse und Schlüssel

Skripte rufen https://mcp.sallyport.cloud/v1 mit einem Konsolenschlüssel auf. Ein Inhaber erstellt ihn unter Einstellungen, API-Schlüssel mit „Neuer API-Schlüssel“. Er beginnt mit sp_ck_ und wird nur einmal angezeigt.

Senden Sie ihn als Authorization: Bearer $SP_CONSOLE_KEY. Der Schlüssel handelt als Inhaber der ganzen Organisation. Er hört auf zu funktionieren, wenn er widerrufen wird oder sein Ersteller kein Inhaber mehr ist.

Einige Aktionen brauchen einen angemeldeten Menschen und beantworten einen Konsolenschlüssel mit 403. Das sind Konsolenschlüssel erstellen, Freigaben beantworten, OAuth-Anmeldung, Benachrichtigungseinstellungen, Signale bestätigen und gespeicherte Antworten herunterladen.

Agent-Token (sp_live_…, sp_test_…) sind für /mcp und /p/. Auf /v1 öffnen sie eine Route: GET /v1/bodies/{body_ref} für die eigenen Aufrufe des Agenten.

export SP_CONSOLE_KEY='sp_ck_…'

curl --fail-with-body \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  https://mcp.sallyport.cloud/v1/tenants/me

curl --fail-with-body \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  https://mcp.sallyport.cloud/v1/workspaces

Antworten und Fehler

Ein Erfolg ist {"data": …, "request_id": "…"} mit 200, oder 201, wenn etwas erstellt wurde. Anfrage-Bodys sind JSON bis 1 MiB. Ein Feld, das die Route nicht kennt, wird ignoriert, außer entfernte Regelfelder wie class_policy auf /bindings, die 422 erhalten.

Ein Fehler hat auf allen Routen dieselbe Form. message ist ein kurzer englischer Satzteil, details trägt, was ein Programm braucht.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": {
      "fields": [
        { "field": "workspace_id", "code": "not_a_uuid", "message": "Select a workspace" }
      ]
    },
    "request_id": "9e8df29b6763e0ddd8138df2790de68a"
  }
}

Listen

Die meisten Listen liefern alle Zeilen auf einmal: data ist {"items": […], "total": n, "page": 1, "limit": n}.

Aufrufe, Freigaben und Audit-Ereignisse kommen in Seiten aus {"items", "next_cursor", "total", "truncated"}. limit ist standardmäßig 50 und höchstens 200. Senden Sie next_cursor als cursor zurück, bis es null ist.

Ein Filter mit mehreren Werten nimmt sie durch Kommas getrennt, etwa state=completed,failed. Die meisten Listenrouten lehnen einen unbekannten Parameter ab, ein falsch geschriebener Filter liefert also nie alles.

Einem Skript einen eigenen Agenten geben

POST /agents nimmt name und workspace_id. environment ist live (Standard) oder test; description, delegate_user_id und allowed_ips sind optional. workspace_id entnehmen Sie GET /workspaces.

Ein neuer Agent erhält sofort alle aktiven Verbindungen seines Arbeitsbereichs und seiner Umgebung, alle ohne Nachfrage. Stellen Sie ihm dann ein Token aus. Das Beispiel liest die ID des neuen Agenten mit jq.

export SP_WORKSPACE_ID='…'

AGENT_ID=$(curl --fail-with-body --silent \
  --request POST \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"name\":\"Nightly report\",\"workspace_id\":\"$SP_WORKSPACE_ID\"}" \
  https://mcp.sallyport.cloud/v1/agents | jq -r .data.id)

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  --header "Content-Type: application/json" \
  --data '{"label":"CI"}' \
  "https://mcp.sallyport.cloud/v1/agents/$AGENT_ID/tokens"

Das Token steht in data.token, und nur in dieser Antwort erscheint es. Es beginnt mit sp_live_ bei einem Live-Agenten und mit sp_test_ bei einem Test-Agenten.

label nimmt bis zu 100 Zeichen, expires_at ist eine optionale RFC-3339-Zeit in der Zukunft. DELETE /agents/{id}/tokens/{token_id} widerruft ein Token.

Einen Schlüssel hinzufügen

POST /credentials speichert einen Schlüssel und legt im selben Schritt seine Verbindungen an. Alle Agenten desselben Arbeitsbereichs und derselben Umgebung erhalten sie sofort.

export GITHUB_TOKEN='…'

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"name\":\"GitHub\",\"workspace_id\":\"$SP_WORKSPACE_ID\",\"recipe_key\":\"github\",\"fields\":{\"value\":\"$GITHUB_TOKEN\"}}" \
  https://mcp.sallyport.cloud/v1/credentials

recipe_key nennt den Dienst, GET /recipes listet sie. fields trägt das Geheimnis unter den Namen aus credential_fields des Rezepts; die meisten Dienste haben ein Feld, value. environment ist standardmäßig live.

Die Antwort beschreibt den Schlüssel ohne sein Geheimnis. data.used_by.bindings listet die neuen Verbindungen: Eine id daraus ist die {binding_id} für den HTTP-Proxy.

Keine Route gibt je ein Geheimnis zurück. Zum Ersetzen senden Sie ein neues fields-Objekt an POST /credentials/{id}/rotate.

Ändern, wie ein Agent eine Verbindung nutzt

Jedes Paar aus Agent und Verbindung hat eine Regel. class_policy ordnet read, write und destructive je auto, ask oder deny zu, und ein neues Paar startet mit allen dreien auf auto.

export SP_BINDING_ID='…'

curl --fail-with-body \
  --request PUT \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  --header "Content-Type: application/json" \
  --data '{"class_policy":{"read":"ask","write":"ask","destructive":"ask"}}' \
  "https://mcp.sallyport.cloud/v1/agents/$AGENT_ID/bindings/$SP_BINDING_ID"

PUT ersetzt die ganze Regel. Eine weggelassene Klasse wird zu ask, und ein weggelassenes step_up, path_prefix_override, methods_override oder rate_per_hour wird gelöscht. Senden Sie die mit, die Sie behalten wollen.

Optionale Felder: step_up (none, oder totp für einen Authenticator-Code bei der Freigabe destruktiver Aufrufe), path_prefix_override, methods_override und rate_per_hour. Die letzten drei können die Verbindung nur enger machen.

DELETE /agents/{id}/bindings/{binding_id} nimmt dem Agenten eine Verbindung. POST /agents/{id}/bindings gibt Verbindungen zurück: binding_ids oder "all": true, optional mit einer rule derselben Form.

Aufrufe und das Protokoll lesen

GET /calls blättert durch die Aufrufe, die neuesten zuerst. Filter: workspace_id, agent_id, binding_id, state, class, decision, channel, host, q, session, from und to.

Ein Aufruf trägt call_id, agent, binding, class, decision (run, ask oder deny), state, summary, upstream_status, duration_ms, Byte-Zahlen, error_code und body_ref.

Zustände: admitted, awaiting_approval, dispatching, executing, completed, denied, failed, outcome_unknown und cancelled. GET /calls/{call_id} ergänzt die Absicht, den Verlauf und die Sequenznummern des Aufrufs im Protokoll.

GET /audit/events blättert durch das Protokoll, das Neueste zuerst. GET /audit/export lädt die Kette als JSON-Zeilen herunter: ein Kopf, dann ein Ereignis pro Zeile. from_seq und to_seq grenzen einen Bereich ein.

Einen Agenten auf bekannte Adressen beschränken

allowed_ips in POST /agents und PATCH /agents/{id} nimmt bis zu 100 IP-Adressen oder CIDR-Bereiche. Eine leere Liste erlaubt jede Adresse, und ein PATCH ohne das Feld behält die aktuelle Liste.

export SP_AGENT_IP='…'

curl --fail-with-body \
  --request PATCH \
  --header "Authorization: Bearer $SP_CONSOLE_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"allowed_ips\":[\"$SP_AGENT_IP\"]}" \
  "https://mcp.sallyport.cloud/v1/agents/$AGENT_ID"

SP_AGENT_IP ist die Adresse, von der die Anfragen des Agenten kommen. GET /me/ip, auf diesem Rechner ausgeführt, zeigt die Adresse, die Sallyport sieht.

Eine Anfrage von jeder anderen Adresse erhält 403 SOURCE_IP_NOT_ALLOWED auf /mcp, /p/ und /v1/bodies. Laufende Aufrufe werden nicht gestoppt.

Verbundene Apps

GET /oauth/consents liefert die KI-Clients, die sich per OAuth angemeldet haben, eine Zeile pro Mensch, Client und Agent. Ein Mitglied bekommt seine eigenen Zeilen; ein Inhaber, ein Administrator oder ein Konsolenschlüssel bekommt alle.

Eine Zeile enthält id, client_id, client_name, registration (cimd für einen Client, den seine Website ausweist, dcr für einen, der sich selbst registriert hat), verified, domain, publisher, redirect (kind: web, app oder loopback, dazu host), agent (id, name), workspace_id, connected_by (id, name, email), connected_at, renewed_at, last_used_at und mine.

DELETE /oauth/consents/{id} trennt die ganze Verbindung. Ihre Aufrufe enden sofort, auf jedem Computer, von dem aus sich der Client angemeldet hat, und der Client kommt nur mit einer neuen Anmeldung zurück.

Der Zustimmungsbildschirm liest GET /oauth/consent?request=…, nur für einen angemeldeten Menschen. Neben Client-ID und Weiterleitungsadresse enthält die Antwort client.verified, client.domain, client.publisher, redirect (kind, host) und workspaces. Jeder Arbeitsbereich hat access: grants (existing, all oder none) und die connections, die der Agent nutzen wird, jede mit id, name, channel und asks_first.

Eine Zeile enthält außerdem sub_agents: die Agenten, die der Client für seine Maschinen angelegt hat, jeder mit id, name und box, der Maschine, für die er da ist. In GET /agents hat ein solcher Agent created_by_client mit client_id, client_name und box. parent_agent_id hat er nur unter einer Verbindung, die selbst ein Agent ist, angelegt mit scope=mcp agents. Jeder andere Agent hat null in beiden. Eine Zeile mit manages_agents: true ist die Verbindung einer Plattform: Sie verwaltet Agenten und ist selbst kein Agent.

Tokens für die Maschinen einer Plattform

Eine Plattform, die Agenten auf eigenen Maschinen betreibt, meldet sich einmal mit scope=agents an. Diese Zustimmung ist ein Zugriff zum Verwalten von Agenten, kein Agent: Die Person sieht eine kurze Karte ohne Dienstliste. Mit dem Access-Token der Verbindung legt sie für jede Maschine einen Agenten an, bei POST https://mcp.sallyport.cloud/v1/agents. Der Agent startet ohne Zugriff: Was er nutzen darf, wählt eine Person auf seiner Seite in der Konsole.

curl -sS https://mcp.sallyport.cloud/v1/agents \
  -H "Authorization: Bearer $SP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "api-worker", "box": "5f0c2d1e-9a4b-4c1e-8f3a-2b7d9e6c1a40"}'

Die Antwort enthält agent_id und access_url, die Zugriffsseite des Agenten. Hängen Sie &return_to= mit Ihrer eigenen Seite an, und die Person kommt mit einem Klick zurück. Eine Maschine hat einen Agenten: Ein zweiter POST antwortet 409 mit box_has_agent. GET /v1/agents listet die Agenten der Person mit created_by_client, box und paused. PATCH und DELETE /v1/agents/{id} benennen um, pausieren oder löschen nur Agenten, die dieser Client angelegt hat. Kein Aufruf dieser API gibt oder nimmt Zugriff. Senden Sie allowed_ips bei POST oder PATCH, und die Tokens des Agenten funktionieren nur von diesen Adressen: Ein von der Maschine kopiertes Token ist überall sonst wertlos. Eine Liste, die die Person in der Konsole setzt, gilt zusätzlich.

Für den Token einer Maschine tauscht die Plattform den Access-Token der Verbindung bei POST https://mcp.sallyport.cloud/token (RFC 8693) und nennt den Agenten in sallyport_agent. Der Token gilt eine Stunde.

curl -sS https://mcp.sallyport.cloud/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d client_id=https://detachbox.com/.well-known/sallyport-client.json \
  -d subject_token="$SP_ACCESS_TOKEN" \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d sallyport_agent="$AGENT_ID"

Die Antwort enthält access_token, expires_in, sallyport_agent_id, sallyport_agent_name und sallyport_agent_url. Einen Refresh-Token gibt es nicht: Die Plattform tauscht erneut. Eine Ablehnung enthält sallyport_reason: subject_token_expired, consent_ended, agents_scope_missing, agent_not_bound, agent_deleted oder agent_paused.

POST https://mcp.sallyport.cloud/revoke (RFC 7009) nimmt token und client_id. Der Token einer Maschine beendet jeden Token dieser Maschine. Der Refresh-Token beendet die ganze Verbindung, wie „Trennen“.

GET https://mcp.sallyport.cloud/v1/access mit Authorization: Bearer antwortet für den Agenten dieses Tokens, den einer Maschine: services, die Zahl der Verbindungen, die er nutzen kann, access_url, seine Zugriffsseite, und connections, dieselben Einträge wie bei list_access. Solange er keine Dienste hat, sagt message das in einer Zeile. Ein Token, der nicht passt, bekommt 401 mit WWW-Authenticate: Bearer und error="invalid_token". Der eigene Token der Verbindung bekommt services: 0 und eine Zeile, dass sie keinen Dienst nutzt. Auf /mcp und /p/ bekommt er 403 mit error="insufficient_scope" und scope="mcp".

Fertige MCP-Server

GET /v1/mcp-servers listet die Remote-MCP-Server, die die Konsole beim Hinzufügen anbietet. Es sind von den Anbietern selbst betriebene Server, jeder mit seiner Adresse und seiner Anmeldeart. Jedes Mitglied kann die Liste lesen. Die Auswahl füllt nur das Formular aus, gespeichert wird eine gewöhnliche Remote-MCP-Verbindung, siehe MCP-Clients und Remote-Server.

{
  "data": {
    "items": [
      {
        "key": "datadog-site",
        "name": "Datadog (other sites)",
        "vendor": "Datadog",
        "url": "https://mcp.{site}/v1/mcp",
        "url_part": {
          "name": "site",
          "label": { "en": "Your Datadog site domain, for example datadoghq.eu or us5.datadoghq.com", "ru": "…", "es": "…", "pt": "…", "fr": "…", "de": "…" },
          "example": "datadoghq.eu"
        },
        "auth": "oauth",
        "dynamic_registration": true,
        "bearer_alternative": false,
        "api_key_header": null,
        "api_key_prefix": null,
        "key_url": null,
        "recipe": "datadog",
        "docs_url": "https://docs.datadoghq.com/mcp_server/setup/",
        "description": { "en": "Query logs, metrics, traces, monitors and incidents on your Datadog site.", "ru": "…", "es": "…", "pt": "…", "fr": "…", "de": "…" }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 1
  },
  "request_id": "5d0c2f7e8a1b4c6d9e0f1a2b3c4d5e6f"
}

Alle Routen

Die Pfade liegen unter https://mcp.sallyport.cloud/v1. Mitglied heißt jede Rolle in der Organisation. Ein Konsolenschlüssel zählt als Inhaber.