Request body
{
"content": {
"application/json": {
"schema": {
"allOf": [
{
"anyOf": [
{
"required": [
"provider",
"external_reference"
]
},
{
"required": [
"account_id"
]
}
]
},
{
"anyOf": [
{
"required": [
"success_redirect_url"
]
},
{
"required": [
"webhook_id"
]
},
{
"required": [
"opener_origin"
]
}
]
}
],
"properties": {
"account_id": {
"description": "Reconnect an existing account in place (mode=reconnect); provider and external_reference are resolved from the account",
"format": "uuid",
"type": "string"
},
"allowed_success_redirect_origin": {
"format": "uri",
"type": "string"
},
"auth_mode": {
"description": "Defaults per provider - qr for socket messaging, oauth for gmail/outlook/linkedin/instagram_business/google/microsoft/github, meta_signup for whatsapp_business, credentials for unofficial instagram, api_token for sentry, managed_session for linkedin_session; browser_session remains its fallback. github's oauth lane is a GitHub App installation redirect rather than an authorization-code exchange.",
"enum": [
"qr",
"phone",
"oauth",
"meta_signup",
"credentials",
"managed_session",
"browser_session",
"api_token"
]
},
"capabilities": {
"description": "Productivity providers only - the capability set to request OAuth scopes for; defaults to project capability_selections",
"items": {
"maxLength": 100,
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"client_state": {
"maxLength": 2048,
"type": "string"
},
"expires_in_seconds": {
"default": 900,
"maximum": 3600,
"minimum": 60,
"type": "integer"
},
"external_reference": {
"description": "Stable caller/team connection identity used for recovery instead of duplication; required unless account_id is provided",
"maxLength": 255,
"type": "string"
},
"failure_redirect_url": {
"description": "Optional destination used only after a terminal hosted-connect failure",
"format": "uri",
"type": "string"
},
"opener_origin": {
"format": "uri",
"type": "string"
},
"provider": {
"description": "Required unless account_id is provided. This is the whole set the route accepts - a provider is listed only once the hosted portal can complete its journey, so a name absent here is a 422.",
"enum": [
"whatsapp",
"telegram",
"gmail",
"outlook",
"linkedin",
"linkedin_session",
"whatsapp_business",
"instagram_business",
"instagram",
"google",
"microsoft",
"github",
"sentry",
"slack",
"dropbox"
]
},
"success_redirect_url": {
"format": "uri",
"type": "string"
},
"sync_policy": {
"description": "For gmail and outlook only: full (default) syncs and stores mail; passive keeps the sign-in alive but stores nothing (read it live through the changes, message, attachment, send and push routes)",
"enum": [
"full",
"passive"
]
},
"webhook_id": {
"description": "Existing signed Kairos webhook; arbitrary callback URLs are rejected",
"format": "uuid",
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
}