Identity: integrations

The integrations this identity has connected, and whether each is healthy

GET /v1/identities/{slug}/integrations · operation listIntegrations

Requires the batondeck:identities:read permission (action identity:read).

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes

Responses

Status	Meaning
200	The integrations this identity has connected, and whether each is healthy
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "integrations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "transport": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "permission": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "slug",
          "transport",
          "endpoint",
          "status",
          "permission"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "integrations"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/identities/:slug/integrations' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Connect an MCP server: a catalogue entry in one click, or any server by its URL (SPEC §6.1-§6.4)

POST /v1/identities/{slug}/integrations · operation createIntegration

Requires the batondeck:identities:manage permission (action integration:write).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes

Request body (application/json)

Field	Type	Required	Notes
catalogue	string		≤ 64 chars
slug	string		≥ 2 chars, ≤ 32 chars
endpoint	string
transport	“streamable-http” \	“sse”
auth	object \	null

Request schema

{
  "type": "object",
  "properties": {
    "catalogue": {
      "type": "string",
      "maxLength": 64
    },
    "slug": {
      "type": "string",
      "minLength": 2,
      "maxLength": 32
    },
    "endpoint": {
      "type": "string",
      "format": "uri"
    },
    "transport": {
      "type": "string",
      "enum": [
        "streamable-http",
        "sse"
      ]
    },
    "auth": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "header": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "value": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            }
          },
          "required": [
            "header",
            "value"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

Responses

Status	Meaning
201	Connect an MCP server: a catalogue entry in one click, or any server by its URL (SPEC §6.1-§6.4)
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

201 response schema

{
  "type": "object",
  "properties": {
    "integration": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": "string"
        },
        "transport": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "permission": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "slug",
        "transport",
        "endpoint",
        "status",
        "permission"
      ],
      "additionalProperties": false
    },
    "tools": {
      "type": "number"
    },
    "trouble": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "authorization_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "integration",
    "tools",
    "trouble",
    "authorization_url"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/identities/:slug/integrations' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Start the upstream OAuth ceremony and hand back the URL to send the owner to

POST /v1/identities/{slug}/integrations/{name}/authorize · operation authorizeIntegration

Requires the batondeck:identities:manage permission (action integration:write).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
name	path	string	yes

Request body (application/json)

Field	Type	Required	Notes
scope	string		≤ 512 chars

Request schema

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "maxLength": 512
    }
  },
  "additionalProperties": false
}

Responses

Status	Meaning
200	Start the upstream OAuth ceremony and hand back the URL to send the owner to
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "authorization_url": {
      "type": "string"
    }
  },
  "required": [
    "authorization_url"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/identities/:slug/integrations/:name/authorize' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

What this integration offers, and what it could offer (SPEC §6.5)

GET /v1/identities/{slug}/integrations/{name}/exposure · operation getExposure

Requires the batondeck:identities:read permission (action identity:read).

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
name	path	string	yes

Responses

Status	Meaning
200	What this integration offers, and what it could offer (SPEC §6.5)
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "catalog": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "version": {
      "type": "number"
    },
    "stale": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "catalog",
    "entries",
    "version",
    "stale"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/identities/:slug/integrations/:name/exposure' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Replace which of an integration’s tools contacts may reach

POST /v1/identities/{slug}/integrations/{name}/exposure · operation setExposure

Requires the batondeck:identities:manage permission (action integration:write).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
name	path	string	yes

Request body (application/json)

Field	Type	Required	Notes
entries	array of object	yes

Request schema

{
  "type": "object",
  "properties": {
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "passthrough",
              "mapped",
              "agent"
            ]
          }
        },
        "required": [
          "tool",
          "mode"
        ],
        "additionalProperties": {}
      }
    }
  },
  "required": [
    "entries"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
200	Replace which of an integration’s tools contacts may reach
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "version": {
      "type": "number"
    }
  },
  "required": [
    "version"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/identities/:slug/integrations/:name/exposure' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Disconnect an upstream and forget its credential

DELETE /v1/identities/{slug}/integrations/{name} · operation deleteIntegration

Requires the batondeck:identities:manage permission (action integration:write).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
name	path	string	yes

Responses

Status	Meaning
200	Disconnect an upstream and forget its credential
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "null"
}

curl -X DELETE 'https://api.batondeck.com/v1/identities/:slug/integrations/:name' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"