Docs
Developer Portal

API reference

Connectors

Add, test, rotate and remove connectors.
Read the Guide
GET/v1/orgs/:orgId/connectors

Lists connectors. Credentials are never returned. Also limit, the plan's maxConnectors.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
connectors:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  connectors: {
    toolCount: number
    omittedTools: number
    oauth?: {
      server: null | string
      registered: boolean | null
      people?: number
      signIn: "user" | "shared"
      connected: boolean
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    lastError?: string
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    signIn?: "user" | "shared"
    lastCheckedAt?: number
  }[]
  limit: number
}
GET/v1/orgs/:orgId/connectors/:connectorId

A connector with its cached tools and the names they have on the MCP server.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
connectors:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectorId

    Connector id (con_…).

Errors

  • 404Connector not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/{connectorId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      server: null | string
      registered: boolean | null
      people?: number
      signIn: "user" | "shared"
      connected: boolean
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    lastError?: string
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    signIn?: "user" | "shared"
    lastCheckedAt?: number
  }
  tools: {
    exposedName: string
    name: string
    title?: string
    description?: string
    inputSchema: {
      [key: string]: unknown
    }
  }[]
}
POST/v1/orgs/:orgId/connectors

Registers a remote MCP server.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
connectors:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • namestringrequired

    1–64 characters. Trimmed.

  • slugstringrequired

    Matches ^[a-z](?:[a-z0-9-]{0,22}[a-z0-9])?$. Trimmed.

  • urlstringrequired

    1–2,048 characters. Trimmed.

  • authType"none" | "bearer" | "header" | "oauth"

    Default "none".

  • transport"http" | "sse"

    Default "http".

  • headerNamestring

    Trimmed.

  • secretstring

    1–4,096 characters. Matches ^[\x20-\x7E]+$. Trimmed.

  • oauthClientIdstring

    1–512 characters. Trimmed.

  • oauthClientSecretstring

    1–4,096 characters. Matches ^[\x20-\x7E]+$. Trimmed.

  • signIn"shared" | "user"

    Default "shared".

Also checked: Enter the credential. Enter a valid header name (for example X-API-Key).

Errors

  • 400An organization can have up to … connectors.
  • 404Connector not found
  • 409Slug "…" is already in use.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "slug": "example",
    "url": "https://example.com"
  }'
Send it from this page with your session or a key.

Response 201

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      server: null | string
      registered: boolean | null
      people?: number
      signIn: "user" | "shared"
      connected: boolean
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    lastError?: string
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    signIn?: "user" | "shared"
    lastCheckedAt?: number
  }
}
POST/v1/orgs/:orgId/connectors/:connectorId/test

Connects to the server and caches its tool list. A failed check keeps the last good list and records the error.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
connectors:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectorId

    Connector id (con_…).

Errors

  • 404Connector not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/{connectorId}/test' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      server: null | string
      registered: boolean | null
      people?: number
      signIn: "user" | "shared"
      connected: boolean
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    lastError?: string
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    signIn?: "user" | "shared"
    lastCheckedAt?: number
  }
}
PATCH/v1/orgs/:orgId/connectors/:connectorId

Renames, enables or disables a connector, or replaces its credential.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
connectors:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectorId

    Connector id (con_…).

Request body

  • namestring

    1–64 characters. Trimmed.

  • enabledboolean
  • secretstring

    1–4,096 characters. Matches ^[\x20-\x7E]+$. Trimmed.

  • signIn"shared" | "user"

Also checked: Nothing to update.

Errors

  • 400Only OAuth connectors have a sign-in mode.
  • 400This connector doesn't use a credential.
  • 404Connector not found
curl -X PATCH 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/{connectorId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "enabled": true,
    "secret": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  connector: {
    toolCount: number
    omittedTools: number
    oauth?: {
      server: null | string
      registered: boolean | null
      people?: number
      signIn: "user" | "shared"
      connected: boolean
    }
    transport: "http" | "sse"
    hasSecret: boolean
    url: string
    name: string
    status?: "ok" | "unknown" | "error"
    createdAt?: number
    updatedAt?: number
    orgId: string
    slug: string
    createdBy: string
    accessExpiresAt?: number
    connectorId: string
    enabled?: boolean
    lastError?: string
    authType: "header" | "none" | "oauth" | "bearer"
    headerName?: string
    signIn?: "user" | "shared"
    lastCheckedAt?: number
  }
}
DELETE/v1/orgs/:orgId/connectors/:connectorId

Deletes a connector.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
connectors:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectorId

    Connector id (con_…).

Errors

  • 404Connector not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/{connectorId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

POST/v1/orgs/:orgId/connectors/:connectorId/oauth/start

OAuth connectors: finds the server's sign-in (and registers a client when the server allows it), stores a one-time state with a PKCE verifier and returns the authorization URL to send the user to.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
connectors:read (for connectors where each person signs in (signIn: "user")), connectors:write (for a shared sign-in)
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectorId

    Connector id (con_…).

Request body

  • returnTostring

    Up to 500 characters.

Errors

  • 400This connector doesn't use OAuth.
  • 403Signing in to a connector needs a signed-in user.
  • 404Connector not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/{connectorId}/oauth/start' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "returnTo": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  url: string
}
POST/v1/orgs/:orgId/connectors/oauth/callback

Completes a connector sign-in: consumes the state (one use; same user and org), exchanges the code, stores the tokens encrypted and checks the connector's tools with them.

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
connectors:read, connectors:read (for connectors where each person signs in (signIn: "user")), connectors:write (for a shared sign-in)
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Request body

  • statestringrequired

    10–300 characters.

  • codestring

    1–4,000 characters.

  • errorstring

    Up to 200 characters.

Errors

  • 403Signing in to a connector needs a signed-in user.
  • 404Connector not found
  • 409Start the sign-in again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/oauth/callback' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  connected: false
  returnTo: string
  connectorId: string
}
| {
  connected: true
  returnTo: string
  connectorId: string
}
DELETE/v1/orgs/:orgId/connectors/:connectorId/oauth/session

Signs out: the caller's own sign-in to a per-person connector, or the shared sign-in (connectors:write).

Auth
A person's token or an API key, as Authorization: Bearer.
Scopes
connectors:read (your own sign-in to a connector where each person signs in), connectors:write (the shared sign-in)
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • connectorId

    Connector id (con_…).

Errors

  • 400This connector doesn't use OAuth.
  • 403Signing in to a connector needs a signed-in user.
  • 404Connector not found
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/connectors/{connectorId}/oauth/session' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body