REST reference · v1

Configure a connection

PUT/v1/workspaces/{workspaceId}/connections/{provider}/{environment}

Provider configure permission; browser_session also requires company owner. Allowed mode depends on catalog provider. Production entitlements/limits apply. Uses a credential reference only; changing settings invalidates previous evidence.

Company permissions

Required OAuth scopes: orchesphere.read, orchesphere.manage. How scopes and company rights work.

Path and header parameters

Name	Location	Required	Allowed values / bounds
`workspaceId`	path	Yes	`string` minLength: 8 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]{8,80}$
`provider`	path	Yes	"quickbooks" \| "netsuite" \| "stripe" \| "paypal" \| "payoneer" \| "us-bank" \| "bank-accounts" \| "plaid" \| "avalara" \| "track1099" \| "thomson-reuters" \| "xero" \| "sage" \| "freshbooks" \| "zoho-books" \| "bill" \| "ramp" \| "brex" \| "expensify" \| "gusto" \| "rippling" \| "square" \| "chargebee" \| "recurly" \| "pipe17" \| "magento" \| "shopify" \| "bigcommerce" \| "salsify" \| "amazon" \| "walmart" \| "ebay" \| "channelengine" \| "mirakl" \| "chewy" \| "sellerboard" \| "sps" \| "netsuite-connector" \| "gs1" \| "orderful" \| "woocommerce" \| "commercetools" \| "prestashop" \| "etsy" \| "tiktok-shop" \| "faire" \| "rithum" \| "klaviyo" \| "amazon-ads" \| "google-ads" \| "shipbob" \| "shipstation" \| "flavorcloud" \| "aftership" \| "ups" \| "fedex" \| "dhl" \| "usps" \| "easypost" \| "shippo" \| "easyship" \| "flexport" \| "dsv" \| "shiphero" \| "entra" \| "sharepoint" \| "onedrive" \| "teams" \| "outlook" \| "outlook-calendar" \| "exchange-fur4" \| "exchange-platformz" \| "google-workspace" \| "jira" \| "confluence" \| "slack" \| "notion" \| "asana" \| "linear" \| "airtable" \| "ipostal" \| "clickup" \| "monday" \| "trello" \| "smartsheet" \| "basecamp" \| "zoom" \| "dropbox" \| "box" \| "docusign" \| "pandadoc" \| "figma" \| "canva" \| "miro" \| "hubspot" \| "salesforce" \| "zendesk" \| "servicenow" \| "mailchimp" \| "mandrill" \| "twilio" \| "sendgrid" \| "brandfolder" \| "strapi" \| "google-analytics" \| "intercom" \| "helpscout" \| "freshdesk" \| "zoho-crm" \| "pipedrive" \| "activecampaign" \| "constant-contact" \| "customer-io" \| "aws" \| "cloudflare" \| "google-cloud" \| "new-relic" \| "plerion" \| "postman" \| "github" \| "azure" \| "digitalocean" \| "vercel" \| "netlify" \| "supabase" \| "firebase" \| "sentry" \| "datadog" \| "grafana" \| "gitlab" \| "bitbucket" \| "docker" \| "snowflake" \| "databricks" \| "bigquery" \| "redshift" \| "mongodb" \| "postgresql" \| "mysql" \| "tableau" \| "power-bi" \| "looker" \| "fivetran" \| "airbyte" \| "dbt" \| "segment" \| "openai" \| "anthropic" \| "gemini" \| "bedrock" \| "azure-openai" \| "perplexity" \| "cohere" \| "hugging-face" \| "elevenlabs" \| "heygen" \| "cursor" pattern: ^[a-z0-9][a-z0-9-]{1,63}$
`environment`	path	Yes	`"production" \| "sandbox"`

Request

JSON body: required.

Field	Type	Required	Description / bounds
`expectedAccountId`	`string`	Yes	minLength: 1 · maxLength: 160
`expectedCompanyName`	`string`	Yes	minLength: 1 · maxLength: 160
`authMode`	`"secrets_manager" \| "agentcore" \| "browser_session"`	Yes	—
`credentialRef`	`string`	No	A company-scoped credential reference, never a provider secret. Omit to retain an existing reference with unchanged authMode; empty string clears it. Browser mode forbids a reference. · maxLength: 512

Complete request schema

{
  "type": "object",
  "properties": {
    "expectedAccountId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "expectedCompanyName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "authMode": {
      "type": "string",
      "enum": [
        "secrets_manager",
        "agentcore",
        "browser_session"
      ]
    },
    "credentialRef": {
      "type": "string",
      "maxLength": 512,
      "description": "A company-scoped credential reference, never a provider secret. Omit to retain an existing reference with unchanged authMode; empty string clears it. Browser mode forbids a reference."
    }
  },
  "required": [
    "expectedAccountId",
    "expectedCompanyName",
    "authMode"
  ],
  "additionalProperties": false
}

http

PUT /v1/workspaces/{workspaceId}/connections/{provider}/{environment} HTTP/1.1
Host: api.orchesphere.ai
Authorization: Bearer <access_token>
Accept: application/json
Content-Type: application/json

{
  "expectedAccountId": "example-account",
  "expectedCompanyName": "Example Company",
  "authMode": "secrets_manager"
}

Use actual IDs returned for your assigned workspace. The example values are fictional. REST v1 accepts no query parameters.

Response · 200

Field	Type	Required	Description / bounds
`connection`	`object`	Yes	—
`reused`	`object`	No	—

Complete response schema

{
  "type": "object",
  "properties": {
    "connection": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{8,80}$",
          "minLength": 8,
          "maxLength": 80
        },
        "version": {
          "type": "integer",
          "minimum": 1
        },
        "provider": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "environment": {
          "type": "string",
          "enum": [
            "production",
            "sandbox"
          ]
        },
        "expectedAccountId": {
          "type": "string"
        },
        "expectedCompanyName": {
          "type": "string"
        },
        "authMode": {
          "type": "string",
          "enum": [
            "secrets_manager",
            "agentcore",
            "browser_session",
            "managed_admin"
          ]
        },
        "hasCredential": {
          "type": "boolean"
        },
        "state": {
          "type": "string",
          "enum": [
            "configured",
            "authentication_required",
            "permission_missing",
            "provider_error",
            "server_unavailable",
            "identity_mismatch",
            "adapter_required",
            "data_read_verified",
            "disconnect_pending"
          ]
        },
        "actualAccountId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualCompanyName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "lastCheckedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "lastReadAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "lastRenewedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "credentialCheckedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "credentialErrorCode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "credentialError": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "errorCode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "allowedActions": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "read",
              "verify",
              "configure",
              "jobs_read_all",
              "jobs_cancel_all"
            ]
          }
        },
        "providerContext": {
          "type": "object",
          "properties": {
            "accountId": {
              "type": "string"
            },
            "environment": {
              "type": "string"
            },
            "roleId": {
              "type": "string"
            },
            "roleName": {
              "type": "string"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "managedExternally": {
          "type": "boolean"
        },
        "managedBy": {
          "type": "string"
        },
        "manageUrl": {
          "type": "string",
          "format": "uri"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "provider",
        "name",
        "environment",
        "expectedAccountId",
        "expectedCompanyName",
        "authMode",
        "hasCredential",
        "state"
      ],
      "additionalProperties": false
    },
    "reused": {
      "const": true
    }
  },
  "required": [
    "connection"
  ],
  "additionalProperties": false
}

json

{
  "connection": {
    "id": "22222222-2222-4222-8222-222222222222",
    "version": 1,
    "provider": "quickbooks",
    "name": "QuickBooks Online",
    "environment": "production",
    "expectedAccountId": "example-account",
    "expectedCompanyName": "Example Company",
    "authMode": "secrets_manager",
    "hasCredential": false,
    "state": "configured",
    "actualAccountId": null,
    "actualCompanyName": null,
    "lastCheckedAt": null,
    "lastReadAt": null,
    "lastRenewedAt": null,
    "credentialCheckedAt": null,
    "credentialErrorCode": null,
    "credentialError": null,
    "errorCode": null,
    "error": null
  }
}

Errors

Status	Meaning
`400`	Invalid path/query/body/header or business validation.
`401`	Missing, expired, revoked, invalid or wrong-resource token.
`402`	Verified company payment is required.
`403`	Insufficient token scope or current company/service/portal/task authority.
`404`	Unknown endpoint or record not found/inaccessible.
`405`	Method is not supported for this path.
`409`	State, quota or idempotency conflict; re-read current state.
`413`	Request exceeds 24,000 bytes.
`415`	Use uncompressed application/json.
`429`	Company job/rate/paid-period allowance reached.
`503`	Temporarily unavailable; a lost mutation response does not prove nothing was saved.

Request limits and recovery · All REST operations