{ "openapi": "3.1.1", "info": { "description": "# Overview\n\nThe AgentKit API gives your AI agents authenticated access to third-party apps — sending emails, reading calendars, creating tickets, querying databases, and more. Your agent calls a tool; Scalekit handles the OAuth flow, token storage, and API call.\n\n**Base URLs:**\n\n```\nhttps://{your-subdomain}.scalekit.dev (Development)\nhttps://{your-subdomain}.scalekit.com (Production)\n```\n\n## Quickstart\n\n### 1. Get an access token\n\nUse your API credentials from the [Scalekit Dashboard](https://app.scalekit.com) → **Developers → Settings → API Credentials**.\n\n```sh\ncurl -X POST https:///oauth/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'client_id={client_id}' \\\n -d 'client_secret={client_secret}' \\\n -d 'grant_type=client_credentials'\n```\n\n### 2. List connected accounts\n\n```sh\ncurl https:///api/v1/connected_accounts \\\n -H 'Authorization: Bearer {access_token}'\n```\n\n### 3. Execute a tool on behalf of a user\n\n```sh\ncurl -X POST https:///api/v1/execute_tool \\\n -H 'Authorization: Bearer {access_token}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"connected_account_id\": \"{connected_account_id}\",\n \"tool_name\": \"gmail_fetch_mails\",\n \"params\": { \"max_results\": 5 }\n }'\n```\n\n## SDKs\n\n```sh\nnpm install @scalekit-sdk/node # Node.js\npip install scalekit-sdk-python # Python\n```\n\nFor the full product guide, see the [AgentKit documentation](https://docs.scalekit.com/agentkit/quickstart/).\n\n---\n\nLooking for SSO, SCIM, directory sync, or user management APIs? See the [SaaSKit API reference](https://docs.scalekit.com/saaskit/apis/). For the complete endpoint list across both products, see [All APIs](https://docs.scalekit.com/apis/).\n", "title": "AgentKit APIs", "contact": { "name": "Scalekit Inc", "url": "https://scalekit.com", "email": "support@scalekit.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "1.0.0", "x-scalar-sdk-installation": [ { "lang": "shell", "description": "Set up OAuth 2.0 Client Credentials authentication to access Scalekit APIs. Includes credential configuration, token exchange, and authenticated API request examples.", "source": "\n# 1. Obtain API Credentials\n# Get your credentials from the Scalekit dashboard\nexport SCALEKIT_ENVIRONMENT_URL=\"https://your-org.scalekit.dev\" # Your Scalekit environment URL\nexport SCALEKIT_CLIENT_ID=\"your_client_id\" # Your client ID\nexport SCALEKIT_CLIENT_SECRET=\"your_client_secret\" # Your client secret\n\n# 2. Exchange client credentials an OAuth 2.0 access token\nTOKEN_RESPONSE=$(curl -s -X POST \"${SCALEKIT_ENVIRONMENT_URL}/oauth/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=${SCALEKIT_CLIENT_ID}\" \\\n -d \"client_secret=${SCALEKIT_CLIENT_SECRET}\" \\\n -d \"grant_type=client_credentials\")\n\n# 3. Make Authenticated API Requests\ncurl -X GET \"${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n -H \"Accept: application/json\"\n" } ] }, "servers": [ { "url": "https://$SCALEKIT_ENVIRONMENT_URL" } ], "security": [ { "oauth2": [] } ], "tags": [ { "name": "Connected Accounts", "description": "Manage connected accounts for third-party integrations and OAuth connections. Connected accounts represent authenticated access to external services like Google, Notion, Slack, and other applications." }, { "name": "Connectors", "description": "Manage built-in and custom connectors (providers) that agents can use to authenticate against third-party services." }, { "name": "Tool Calling", "description": "Execute tools on behalf of users via their connected accounts. Supports both named/pre-defined tools and custom API proxy calls." }, { "name": "MCP Configurations", "description": "Create and manage reusable MCP configurations." } ], "externalDocs": { "description": "AgentKit Docs", "url": "https://docs.scalekit.com/agentkit/quickstart/" }, "paths": { "/api/v1/connected_accounts": { "get": { "description": "Retrieves a paginated list of connected accounts for third-party integrations. Filter by organization, user, connector type, provider, or identifier. Returns OAuth tokens, API keys, and connection status for each account. Use pagination tokens to navigate through large result sets.", "tags": [ "Connected Accounts" ], "summary": "List connected accounts", "operationId": "ConnectedAccountService_ListConnectedAccounts", "parameters": [ { "schema": { "type": "string" }, "description": "Filter by organization ID. Returns only connected accounts associated with this organization.", "name": "organization_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter by user ID. Returns only connected accounts associated with this user.", "name": "user_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter by connector type (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "name": "connector", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter by account identifier. The unique identifier for the connected account within the third-party service (e.g., email address, workspace ID).", "name": "identifier", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter by OAuth provider. The authentication provider name such as 'google', 'microsoft', 'github', etc.", "name": "provider", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of connected accounts to return, up to 99. Defaults to 10 when omitted or 0.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page.", "name": "page_token", "in": "query" }, { "schema": { "type": "string" }, "description": "Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive.", "name": "query", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter by one or more connection names (exact match). Returns connected accounts belonging to any of the specified connections. Max 20 names per request. Cannot be combined with the `connector` field.", "name": "connection_names", "in": "query" }, { "schema": { "type": "boolean" }, "description": "Set to `true` to return only the shared credential of an org-wide connection, or `false` to return only users' own accounts. Omit it to return both.", "name": "is_org_wide_credential", "in": "query" } ], "responses": { "200": { "description": "The connected accounts that match, with each account's status. Credentials are never included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsListConnectedAccountsResponse" } } } }, "400": { "description": "Invalid request - occurs when query parameters are malformed or validation fails", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.connectedAccounts.listConnectedAccounts({\n organizationId: 'org_123',\n pageSize: 20,\n})\nconst connectedAccounts = response.connectedAccounts" }, { "label": "Python SDK", "lang": "python", "source": "response = scalekit_client.connected_accounts.list_connected_accounts(\n organization_id=\"org_123\",\n page_size=20,\n)\n# with_call returns (response, call)\nconnected_accounts = response[0].connected_accounts" }, { "label": "Go SDK", "lang": "go", "source": "// Connected Accounts are not available in the Go SDK public API yet.\n// Use the REST API (GET /api/v1/connected_accounts) or the Node.js/Python SDKs." }, { "label": "Java SDK", "lang": "java", "source": "// Connected Accounts are not part of the Java SDK public API yet.\n// Use the REST API (GET /api/v1/connected_accounts) or the Node.js/Python SDKs." } ] }, "put": { "description": "Updates authentication credentials and configuration for an existing connected account. Modify OAuth tokens, refresh tokens, access scopes, or API configuration settings. Specify the account by ID, or by combination of organization/user, connector, and identifier. Returns the updated account with new token expiry and status information.", "tags": [ "Connected Accounts" ], "summary": "Update connected account credentials", "operationId": "ConnectedAccountService_UpdateConnectedAccount", "responses": { "200": { "description": "Connected account updated successfully with new credentials or configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsUpdateConnectedAccountResponse" } } } }, "400": { "description": "Invalid request - missing required fields, invalid authorization details, or validation failed", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Connected account not found - the specified account does not exist", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsUpdateConnectedAccountRequest" } } }, "required": true } }, "post": { "description": "Creates a connected account for one user and one connection, with credentials your app already holds: OAuth tokens, or an API key or other static credentials. To have the user connect their own account instead, send them an authorization link. Returns the account with its ID and status.", "tags": [ "Connected Accounts" ], "summary": "Create a connected account", "operationId": "ConnectedAccountService_CreateConnectedAccount", "responses": { "200": { "description": "Connected account created successfully with authentication credentials stored securely", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsCreateConnectedAccountResponse" } } } }, "400": { "description": "Invalid request - missing required fields, invalid authorization details, or validation failed. Error code `RESOURCE_ALREADY_EXISTS` when the user already has a connected account on this connection; update it instead.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no connection with this name exists in the environment. Error code `RESOURCE_NOT_FOUND`.", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsCreateConnectedAccountRequest" } } }, "required": true } } }, "/api/v1/connected_accounts/auth": { "get": { "description": "Retrieves complete authentication details for a connected account including OAuth tokens, refresh tokens, scopes, and API configuration. Query by account ID or by combination of organization/user, connector, and identifier. Returns sensitive credential information - use appropriate access controls.", "tags": [ "Connected Accounts" ], "summary": "Get connected account auth credentials", "operationId": "ConnectedAccountService_GetConnectedAccountAuth", "parameters": [ { "schema": { "type": "string" }, "description": "An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set.", "name": "organization_id", "in": "query" }, { "schema": { "type": "string" }, "description": "A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set.", "name": "user_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "name": "connector", "in": "query" }, { "schema": { "type": "string" }, "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", "name": "identifier", "in": "query" }, { "schema": { "type": "string" }, "description": "Unique identifier for the connected account", "name": "id", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved connected account with full authentication details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse" } } } }, "400": { "description": "Invalid request - missing required query parameters", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Connected account not found - no account matches the specified criteria", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connected_accounts/details": { "get": { "description": "Returns metadata for a connected account including status, connector type, provider, and configuration without exposing stored authorization credentials. Look up by account ID, or by a combination of organization (or user), connector, and external identifier.", "tags": [ "Connected Accounts" ], "summary": "Get connected account metadata", "operationId": "ConnectedAccountService_GetConnectedAccountDetails", "parameters": [ { "schema": { "type": "string" }, "description": "An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set.", "name": "organization_id", "in": "query" }, { "schema": { "type": "string" }, "description": "A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set.", "name": "user_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "name": "connector", "in": "query" }, { "schema": { "type": "string" }, "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", "name": "identifier", "in": "query" }, { "schema": { "type": "string" }, "description": "Unique identifier for the connected account", "name": "id", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved connected account details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsGetConnectedAccountByIdentifierResponse" } } } }, "400": { "description": "Invalid request - missing required query parameters", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Connected account not found - no account matches the specified criteria", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connected_accounts/magic_link": { "post": { "description": "Creates a one-time authorization link for connecting or re-authorizing a user's account on one connection, creating the connected account first if it doesn't exist. The link takes the user to the app's consent screen, or to a form for their credentials. Returns the link and when it expires, 5 minutes after you create it.", "tags": [ "Connected Accounts" ], "summary": "Get an authorization link", "operationId": "ConnectedAccountService_GetMagicLinkForConnectedAccount", "responses": { "200": { "description": "Authorization link created, with its expiry time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse" } } } }, "400": { "description": "Invalid request - missing required parameters, or a malformed connected account ID", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no connection with this name exists in the environment. Error code `RESOURCE_NOT_FOUND`.", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountRequest" } } }, "required": true } } }, "/api/v1/connected_accounts/user/verify": { "post": { "description": "Confirms the user assertion and activates the connected account after the user completes third-party OAuth. Called by the B2B app server with auth_request_id and identifier. Validates that the asserted identifier matches the one stored on the auth request and promotes pending tokens to live.", "tags": [ "Connected Accounts" ], "summary": "Verify connected account user", "operationId": "ConnectedAccountService_VerifyConnectedAccountUser", "responses": { "200": { "description": "Verification successful; connected account is now ACTIVE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsVerifyConnectedAccountUserResponse" } } } }, "400": { "description": "Invalid request - missing or malformed fields", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Unauthorized - invalid or missing access token", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Forbidden - identifier mismatch", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no pending flow for the given auth_request_id or already consumed", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsVerifyConnectedAccountUserRequest" } } }, "required": true } } }, "/api/v1/connected_accounts:delete": { "post": { "description": "Deletes the account and the credentials Scalekit stores for it. It doesn't revoke the user's grant at the app. Identify the account by ID, or by its connector and identifier. This can't be undone.", "tags": [ "Connected Accounts" ], "summary": "Delete a connected account", "operationId": "ConnectedAccountService_DeleteConnectedAccount", "responses": { "200": { "description": "Connected account deleted, with the credentials Scalekit stored for it", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid request - malformed parameters or validation failed. Error code `MCP_SERVER_EXISTS_FOR_CONNECTED_ACCOUNT` when a Virtual MCP server instance for this user still uses the account; delete that Virtual MCP server first.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Connected account not found - the specified account does not exist", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsDeleteConnectedAccountRequest" } } }, "required": true } } }, "/api/v1/connected_accounts:search": { "get": { "description": "Search for connected accounts in your environment using a text query that matches against identifiers, providers, or connectors. The search performs case-insensitive matching across account details. Returns paginated results with account status and authentication type information.", "tags": [ "Connected Accounts" ], "summary": "Search connected accounts", "operationId": "ConnectedAccountService_SearchConnectedAccounts", "parameters": [ { "schema": { "type": "string" }, "description": "Search term to match against connected account identifiers, providers, or connectors. Must be at least 3 characters. Case insensitive.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of connected accounts to return per page. Value must be between 1 and 30.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Token from a previous response for pagination. Provide this to retrieve the next page of results.", "name": "page_token", "in": "query" }, { "schema": { "type": "string" }, "description": "Connection ID to filter connected accounts", "name": "connection_id", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved matching connected accounts with pagination support", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsSearchConnectedAccountsResponse" } } } }, "400": { "description": "Invalid request - query parameter is too short (minimum 3 characters) or validation failed", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/custom-providers": { "post": { "description": "Creates an environment-scoped custom provider (connector) with authentication patterns and optional proxy configuration. The returned identifier must be used for all subsequent update and delete operations on this provider.", "tags": [ "Connectors" ], "summary": "Create a custom provider", "operationId": "ProviderService_CreateCustomProvider", "responses": { "200": { "description": "Returns the newly created custom provider, including its system-generated identifier and configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providersCreateProviderResponse" } } } }, "400": { "description": "Invalid request - the provider payload failed validation (e.g. missing required fields or invalid proxy URL)", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Details of the custom connected app provider to create. Identifier is derived by the system and the identifier returned in the response must be used for update and delete operations.", "$ref": "#/components/schemas/v1providersCreateCustomProvider" } } }, "required": true } } }, "/api/v1/custom-providers/{identifier}": { "put": { "description": "Updates an existing environment-scoped custom provider (connector) by its identifier. Only the fields provided in the request are modified.", "tags": [ "Connectors" ], "summary": "Update a custom provider", "operationId": "ProviderService_UpdateCustomProvider", "parameters": [ { "schema": { "type": "string" }, "description": "Identifier of the custom connected app provider to update.", "name": "identifier", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the updated custom provider with its current configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providersUpdateProviderResponse" } } } }, "400": { "description": "Invalid request - the update payload failed validation", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - no custom provider exists with the given identifier", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Fields to update for the custom connected app provider. This aligns with the create custom provider payload.", "$ref": "#/components/schemas/v1providersUpdateCustomProvider" } } }, "required": true } }, "delete": { "description": "Deletes an environment-scoped custom provider (connector) by its identifier. This operation is permanent and removes the provider definition from the environment.", "tags": [ "Connectors" ], "summary": "Delete a custom provider", "operationId": "ProviderService_DeleteCustomProvider", "parameters": [ { "schema": { "type": "string" }, "name": "identifier", "in": "path", "required": true } ], "responses": { "200": { "description": "The custom provider was successfully deleted (no content returned)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providersDeleteProviderResponse" } } } }, "400": { "description": "Invalid request - error code `PROVIDER_HAS_EXISTING_CONNECTIONS` when a connection still uses the connector. Delete its connections first.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - no custom provider exists with the given identifier", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/execute_tool": { "post": { "description": "Executes a tool action using authentication credentials from a connected account. Specify the tool by name and provide required parameters as JSON. The connected account can be identified by ID, or by combination of organization/user, connector, and identifier. Returns the execution result data and a unique execution ID for tracking. Use this endpoint to perform actions like sending emails, creating calendar events, or managing resources in external services.", "tags": [ "Tool Calling" ], "summary": "Execute a tool using a connected account", "operationId": "ToolService_ExecuteTool", "responses": { "200": { "description": "Tool executed successfully with result data and execution ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsExecuteToolResponse" } } } }, "400": { "description": "Invalid request - error code `INVALID_ARGUMENT` when the tool name is missing, the input doesn't match the tool's schema, the connected account belongs to a different app than the tool, or the account isn't `ACTIVE`. Error code `TOOL_ERROR` when the app rejected the call; `tool_error_info.tool_error_code` is `INVALID_ARGUMENT`, `EXECUTION_ERROR`, `INTERNAL_ERROR` or, for a tool from an app's MCP server, `TOOL_ERROR`, and `tool_error_message` has the app's message.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Error code `UNAUTHENTICATED` when your access token is missing, invalid or expired; get a new token and retry. Error code `TOOL_ERROR` with `tool_error_code` `REAUTHENTICATION_NEEDED` or `UNAUTHENTICATED` when the user's access to the app was revoked or expired; send the user a new authorization link.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Error code `TOOL_ERROR` with `tool_error_code` `FORBIDDEN` or `PERMISSION_DENIED` - the app refused the call. The account's credentials are valid but lack the scope this tool needs. The connected account stays `ACTIVE`; grant the missing scope on the connection, have the user authorize again, then retry.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the tool or the connected account doesn't exist. Error code `TOOL_ERROR` with `tool_error_code` `RESOURCE_NOT_FOUND` when the app couldn't find what the call refers to, such as an event ID.", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Error code `TOOL_ERROR` with `tool_error_code` `RATE_LIMITED` - the app rate-limited the call. Back off and retry.", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Error code `TOOL_ERROR` with `tool_error_code` `INTERNAL_ERROR` when Scalekit couldn't run the tool, for example because the connection's auth type isn't supported for this tool. For a tool from an app's MCP server, `tool_error_code` `TOOL_ERROR` when that server failed, rate-limited the call or couldn't be reached; its status is in `tool_error_message`. A retry can run the tool twice, so retry only tools that are safe to repeat, and quote `execution_id` to support.", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsExecuteToolRequest" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.tools.executeTool({\n toolName: 'gmail_send_message',\n identifier: 'user@example.com',\n params: {\n to: 'team@example.com',\n subject: 'Hello from Scalekit',\n body: 'Tool execution succeeded.',\n },\n})" }, { "label": "Python SDK", "lang": "python", "source": "response = scalekit_client.tools.execute_tool(\n tool_name=\"gmail_send_message\",\n identifier=\"user@example.com\",\n params={\n \"to\": \"team@example.com\",\n \"subject\": \"Hello from Scalekit\",\n \"body\": \"Tool execution succeeded.\",\n },\n)" }, { "label": "Go SDK", "lang": "go", "source": "// Tool calling (execute_tool) is not available in the Go SDK public API yet.\n// Use the REST API (POST /api/v1/execute_tool) or the Node.js/Python SDKs." }, { "label": "Java SDK", "lang": "java", "source": "// Tool calling (execute_tool) is not part of the Java SDK public API yet.\n// Use the REST API (POST /api/v1/execute_tool) or the Node.js/Python SDKs." } ] } }, "/api/v1/mcp/configs": { "get": { "description": "Lists MCP configurations for the current environment. Filter by ID, exact name, provider or MCP server URL, or pass `search` to match part of the name.", "tags": [ "MCP Configurations" ], "summary": "List MCP configurations", "operationId": "McpService_ListMcpConfigs", "parameters": [ { "schema": { "type": "string" }, "description": "Filter by MCP configuration id", "name": "filter.id", "in": "query" }, { "schema": { "type": "string" }, "description": "Case-insensitive exact match on configuration name. Allowed characters: letters (a–z, A–Z), digits (0–9), hyphens (-), and underscores (_). Maximum 100 characters.", "name": "filter.name", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter configs that include this provider", "name": "filter.provider", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter configs by MCP server URL. The UUID is extracted from the last path segment of the URL and used to find the matching configuration.", "name": "filter.mcp_server_url", "in": "query" }, { "schema": { "type": "string" }, "description": "Look ahead text search on config name", "name": "search", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "Number of configs to return per page (max 30)", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token to fetch the next or previous page", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "Paginated list of MCP configurations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpListMcpConfigsResponse" } } } }, "400": { "description": "Invalid request - bad filter or pagination parameters", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": {} } } } } }, "post": { "description": "Creates a new MCP configuration with a set of connections and tools.", "tags": [ "MCP Configurations" ], "summary": "Create a new MCP configuration", "operationId": "McpService_CreateMcpConfig", "responses": { "200": { "description": "The newly created MCP configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpCreateMcpConfigResponse" } } } }, "400": { "description": "Invalid request - missing required fields or invalid connection/tool mappings", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "MCP configuration details to create", "$ref": "#/components/schemas/mcpMcpConfig" } } }, "required": true } } }, "/api/v1/mcp/configs/{config_id}": { "get": { "description": "Returns a single MCP configuration for the current environment by ID.", "tags": [ "MCP Configurations" ], "summary": "Fetch an MCP configuration", "operationId": "McpService_GetMcpConfig", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the MCP configuration to fetch", "name": "config_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The requested MCP configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpGetMcpConfigResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - MCP configuration does not exist", "content": { "application/json": { "schema": {} } } } } }, "put": { "description": "Updates the description and connection-to-tool mappings for an existing MCP configuration. The configuration name cannot be changed after creation.", "tags": [ "MCP Configurations" ], "summary": "Update an existing MCP configuration", "operationId": "McpService_UpdateMcpConfig", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the MCP configuration to update", "name": "config_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The updated MCP configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpUpdateMcpConfigResponse" } } } }, "400": { "description": "Invalid request - malformed payload or invalid mappings", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - MCP configuration does not exist", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServiceUpdateMcpConfigBody" } } }, "required": true } }, "delete": { "description": "Deletes the MCP configuration and any associated mappings and instances in the current environment.", "tags": [ "MCP Configurations" ], "summary": "Delete an MCP configuration", "operationId": "McpService_DeleteMcpConfig", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the MCP configuration to delete", "name": "config_id", "in": "path", "required": true } ], "responses": { "200": { "description": "MCP configuration and associated data deleted successfully", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - MCP configuration does not exist", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/mcp/configs/{config_id}/connected_accounts": { "post": { "description": "Returns the connected account state for each connection in the MCP configuration for the given user identifier. When include_auth_link is true, creates connected accounts on the fly if they do not exist and returns a fresh authentication link per connection. When include_auth_link is false or omitted, returns the current status of existing connected accounts only — no accounts are created and authentication_link is always empty. Authentication links are only present when the connection has an associated key; if the connection has no key, authentication_link is empty regardless of include_auth_link.", "tags": [ "MCP Configurations" ], "summary": "List connected accounts for an MCP configuration", "operationId": "McpService_ListMcpConnectedAccounts", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the MCP configuration", "name": "config_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Connected account state returned for each connection in the configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpListMcpConnectedAccountsResponse" } } } }, "400": { "description": "Bad request - config_id or identifier is missing or invalid", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no MCP configuration exists with the given config_id", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServiceListMcpConnectedAccountsBody" } } }, "required": true } } }, "/api/v1/mcp/configs/{mcp_config_id}/tokens": { "post": { "description": "Mints a short-lived JWT that represents a user identifier across the connected accounts associated with an MCP configuration. The supplied identifier becomes the token's `sub` claim; the token's `aud` claim is the MCP server URL bound to the configuration. Claims also carry the MCP configuration ID (`mcp_cfg`) and the list of resolved connected-account IDs (`ca_ids`). Use this operation to issue a single credential an MCP server can present on the user's behalf when calling provider tools. The mint fails if any connection mapped to the configuration has no active connected account for the identifier.", "tags": [ "MCP Configurations" ], "summary": "Create an MCP session token", "operationId": "McpService_CreateMcpSessionToken", "parameters": [ { "schema": { "type": "string" }, "description": "Unique ID of the MCP configuration whose connections back the token. The configuration must exist in the caller's environment.", "name": "mcp_config_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Token created successfully; returns the signed JWT and its absolute expiry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpCreateMcpSessionTokenResponse" } } } }, "400": { "description": "Invalid request - mcp_config_id or identifier is missing or malformed, expiry is outside the 60s-24h window, the MCP configuration has no connections, or a connection has no active connected account for the supplied identifier", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - no MCP configuration exists with the supplied ID in the caller's environment", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServiceCreateMcpSessionTokenBody" } } }, "required": true } } }, "/api/v1/mcp/connections/{key_id}/tokens": { "post": { "description": "Mints a short-lived token for one user that an MCP client sends to one connection's MCP server, at `/mcp/v3/connections/{key_id}`, without a Virtual MCP server. The token's `sub` claim is the identifier and its `aud` claim is that server URL, so the token works only there. Use it when an agent needs the tools of exactly one connection.", "tags": [ "MCP Configurations" ], "summary": "Create an MCP session token for a connection", "operationId": "McpService_CreateMcpConnectionSessionToken", "parameters": [ { "schema": { "type": "string" }, "description": "The connection name, as shown in AgentKit > Connections. It's also the last path segment of the connection's MCP server URL.", "name": "key_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Token created successfully; returns the signed JWT and its absolute expiry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcpCreateMcpSessionTokenResponse" } } } }, "400": { "description": "Invalid request - `key_id` or `identifier` is missing or malformed, `expiry` is outside the 60s-24h window, or the connection isn't an AgentKit connection. When the user has no active account on the connection yet, Scalekit creates a pending one and still returns a token, so the user can authorize from the MCP client.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no active connection with this name exists in the environment.", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServiceCreateMcpConnectionSessionTokenBody" } } }, "required": true } } }, "/api/v1/tools": { "get": { "description": "Workspace catalog. Fetch tools by provider, identifier, and connector. Use this when you need every tool in the environment, not tools bound to one user. If `filter.summary` is true, returns only tool names.", "tags": [ "Tool Calling" ], "summary": "List tools", "operationId": "ToolService_ListTools", "parameters": [ { "schema": { "type": "boolean" }, "description": "Return only tool names instead of full tool details", "name": "filter.summary", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter by tool provider", "name": "filter.provider", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter by connected account identifier", "name": "filter.identifier", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter by one or more tool names", "name": "filter.tool_name", "in": "query" }, { "schema": { "type": "string" }, "description": "Full-text search query to match tools by name or description (e.g., \"gmail get attachment\")", "name": "filter.query", "in": "query" }, { "schema": { "type": "string" }, "description": "Connector name (e.g., 'My Gmail'). When set together with filter.identifier, resolves to a specific connected account and includes its custom MCP tools in the response.", "name": "filter.connector", "in": "query" }, { "schema": { "type": "string" }, "description": "Organization ID to scope the connected account lookup", "name": "filter.organization_id", "in": "query" }, { "schema": { "type": "string" }, "description": "User ID to scope the connected account lookup", "name": "filter.user_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Connected account ID. Alternative to filter.identifier + filter.connector for directly identifying the connected account whose custom MCP tools should be included.", "name": "filter.connected_account_id", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of tools to return per page", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Token from a previous response for pagination", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "Paginated list of tools matching the filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsListToolsResponse" } } } }, "400": { "description": "Invalid request - malformed filter or pagination parameters", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.tools.listTools({\n pageSize: 50,\n filter: { query: 'send message' },\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.tools.tools_pb2 import Filter\n\nresponse = scalekit_client.tools.list_tools(\n filter=Filter(query=\"send message\"),\n page_size=50,\n)" }, { "label": "Go SDK", "lang": "go", "source": "// List tools is not available in the Go SDK public API yet.\n// Use GET /api/v1/tools or the Node.js/Python SDKs." }, { "label": "Java SDK", "lang": "java", "source": "// List tools is not part of the Java SDK public API yet.\n// Use GET /api/v1/tools or the Node.js/Python SDKs." } ] } }, "/api/v1/tools/scoped": { "get": { "description": "Tools already bound to one connected-account identifier. Use this when you need the list a user or agent is authorized to call (the list you pass to an LLM). Filter by provider, tool name, or connection name. `identifier` is required.", "tags": [ "Tool Calling" ], "summary": "List scoped tools", "operationId": "ToolService_ListScopedTools", "parameters": [ { "schema": { "type": "string" }, "description": "Identifier of the connected account to filter tools", "name": "identifier", "in": "query", "required": true }, { "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter by one or more tool providers", "name": "filter.providers", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter by one or more tool names", "name": "filter.tool_names", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter by one or more connection names", "name": "filter.connection_names", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of tools to return per page", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Token from a previous response for pagination", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "Paginated list of tools scoped to the given connected account identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsListScopedToolsResponse" } } } }, "400": { "description": "Invalid request - missing identifier or malformed filter/pagination parameters", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.tools.listScopedTools('user@example.com', {\n filter: {\n connectionNames: ['github-connect'],\n },\n pageSize: 50,\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.tools.tools_pb2 import ScopedToolFilter\n\nresponse = scalekit_client.tools.list_scoped_tools(\n \"user@example.com\",\n filter=ScopedToolFilter(\n connection_names=[\"github-connect\"],\n ),\n page_size=50,\n)" }, { "label": "Go SDK", "lang": "go", "source": "// List scoped tools is not available in the Go SDK public API yet.\n// Use GET /api/v1/tools/scoped or the Node.js/Python SDKs." }, { "label": "Java SDK", "lang": "java", "source": "// List scoped tools is not part of the Java SDK public API yet.\n// Use GET /api/v1/tools/scoped or the Node.js/Python SDKs." } ] } }, "/api/v1/tools/available": { "get": { "description": "Tools that can be made available for a connected-account identifier. Use this when you need the candidate set for an identifier, not the tools already scoped to it. `identifier` is required. Distinct from GET /api/v1/tools/scoped.", "tags": [ "Tool Calling" ], "summary": "List available tools", "operationId": "ToolService_ListAvailableTools", "parameters": [ { "schema": { "type": "string" }, "description": "Identifier of the connected account to list available tools for", "name": "identifier", "in": "query", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of tools to return per page", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Token from a previous response for pagination", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "Paginated list of tools available for the identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsListAvailableToolsResponse" } } } }, "400": { "description": "Invalid request - missing or malformed identifier", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Identifier not found", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.tools.listAvailableTools('user@example.com', {\n pageSize: 50,\n})" }, { "label": "Python SDK", "lang": "python", "source": "# list_available_tools is not in the Python SDK.\n# Use GET /api/v1/tools/available?identifier=user@example.com&page_size=50" }, { "label": "Go SDK", "lang": "go", "source": "// List available tools is not available in the Go SDK public API yet.\n// Use GET /api/v1/tools/available or the Node.js SDK." }, { "label": "Java SDK", "lang": "java", "source": "// List available tools is not part of the Java SDK public API yet.\n// Use GET /api/v1/tools/available or the Node.js SDK." } ] } }, "/api/v1/tools:search": { "post": { "description": "Ranks tools in the environment against a natural-language query and returns the best matches, drawn from every connection enabled in the environment. Pass `identifier` to also annotate each result with per-connection readiness (`TOOL_READINESS_STATE_READY`, `TOOL_READINESS_STATE_NEEDS_CONNECTION`, `TOOL_READINESS_STATE_NEEDS_REAUTH`) for that identifier, so you can gate execution on the right auth step before calling ExecuteTool. An empty `connections` array means the identifier has no connection at all for that tool's provider -- not an error, and distinct from `TOOL_READINESS_STATE_NEEDS_CONNECTION` (a connected account exists but is inactive).", "tags": [ "Tool Calling" ], "summary": "Search tools by query", "operationId": "ToolService_SearchTools", "responses": { "200": { "description": "Ranked tools matching the query, with per-identifier readiness when an identifier is supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsSearchToolsResponse" } } } }, "400": { "description": "Invalid request - the query is empty or exceeds the maximum length", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsSearchToolsRequest" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "import { ToolReadinessState } from '@scalekit-sdk/node'\n\nconst res = await scalekit.tools.searchTools('send a message to a slack channel', {\n identifier: 'user@example.com',\n topK: 10,\n})\n\nfor (const tool of res.tools) {\n console.log(tool.name, tool.score)\n for (const connection of tool.connections) {\n // readinessState is a number at runtime -- always compare against the\n // named enum constant, never a raw number or a string.\n const isReady = connection.readinessState === ToolReadinessState.READY\n console.log(' ', connection.connectionName, isReady, connection.connectedAccountId)\n }\n}" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.tools.tools_pb2 import TOOL_READINESS_STATE_READY\n\nresponse = scalekit_client.tools.search_tools(\n query=\"send a message to a slack channel\",\n identifier=\"user@example.com\",\n top_k=10,\n)\n\nfor tool in response[0].tools:\n print(tool.name, tool.score)\n for connection in tool.connections:\n # readiness_state is an int at runtime -- always compare against the\n # named enum constant, never a raw int or a string.\n is_ready = connection.readiness_state == TOOL_READINESS_STATE_READY\n print(\" \", connection.connection_name, is_ready, connection.connected_account_id)" }, { "label": "Go SDK", "lang": "go", "source": "// Search tools is not available in the Go SDK public API yet.\n// Use POST /api/v1/tools:search or the Node.js/Python SDKs." }, { "label": "Java SDK", "lang": "java", "source": "// Search tools is not part of the Java SDK public API yet.\n// Use POST /api/v1/tools:search or the Node.js/Python SDKs." } ] } } }, "webhooks": { "connected_account.created": { "post": { "summary": "Connected Account Created", "description": "Triggered when a new connected account is created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_101531404017336586", "type": "connected_account.created", "object": "ConnectedAccount", "occurred_at": "2025-12-01T10:23:52.702980847Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_100668583155073286", "id": "ca_101531404000559370", "identifier": "Bruce", "provider": "CANVA", "status": "PENDING_AUTH" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.updated": { "post": { "summary": "Connected Account Updated", "description": "Triggered when a connected account is updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_101652975398683158", "type": "connected_account.updated", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:31:34.895815554Z", "environment_id": "env_88640229614813449", "display_name": "Connected account updated", "data": { "authorization_type": "OAUTH", "connection_id": "conn_100510054016352776", "id": "ca_100510623602835982", "identifier": "Pranesh", "provider": "SUPABASE", "status": "PENDING_AUTH" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.status_updated": { "post": { "summary": "Connected Account Status Updated", "description": "Triggered when a connected account's status changes between two states (for example PENDING_AUTH to ACTIVE, ACTIVE to EXPIRED, or any state to DISCONNECTED). Not triggered on account creation.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountStatusUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_101652975398683158", "type": "connected_account.status_updated", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:31:34.895815554Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_133400101014995480", "connection_name": "gmail", "id": "ca_133400349586228019", "identifier": "john@acmecorp.com", "provider": "GMAIL", "status": "EXPIRED", "old_status": "ACTIVE" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.deleted": { "post": { "summary": "Connected Account Deleted", "description": "Triggered when a connected account is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_101653010731500290", "type": "connected_account.deleted", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:31:55.954027187Z", "environment_id": "env_88640229614813449", "display_name": "connected account deleted", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649788113519113", "identifier": "Clark", "last_used_at": "2025-12-02T06:00:01.374253Z", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:59:57.237447Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.magic_link_generated": { "post": { "summary": "Connected Account Magic Link Generated", "description": "Triggered when an authorization link is created for a user", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountMagicLinkGeneratedEvent" }, "example": { "spec_version": "1", "id": "evt_101652975398683158", "type": "connected_account.magic_link_generated", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:31:34.895815554Z", "environment_id": "env_88640229614813448", "data": { "authorization_type": "OAUTH", "connection_id": "conn_100510054016352776", "id": "ca_100510623602835982", "identifier": "Pranesh", "provider": "SUPABASE", "status": "PENDING_AUTH" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.oauth_tokens_fetched": { "post": { "summary": "Connected Account OAuth Tokens Fetched", "description": "Triggered when OAuth tokens are successfully fetched", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountOauthTokensFetchedEvent" }, "example": { "spec_version": "1", "id": "evt_101649795042509316", "type": "connected_account.oauth_tokens_fetched", "object": "ConnectedAccount", "occurred_at": "2025-12-02T05:59:59.250126407Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649788113519113", "identifier": "Clark", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:59:57.237447778Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.token_refresh_succeeded": { "post": { "summary": "Connected Account Token Refresh Succeeded", "description": "Triggered when token refresh succeeds", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountTokenRefreshSucceededEvent" }, "example": { "spec_version": "1", "id": "evt_101651946317808143", "type": "connected_account.token_refresh_succeeded", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:21:21.517480021Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101644170698948883", "identifier": "Pranesh", "last_used_at": "2025-12-02T06:21:21.393723232Z", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T07:21:20.508197312Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.token_refresh_failed": { "post": { "summary": "Connected Account Token Refresh Failed", "description": "Triggered when token refresh fails", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountTokenRefreshFailedEvent" }, "example": { "spec_version": "1", "id": "evt_101649795042509316", "type": "connected_account.token_refresh_failed", "object": "ConnectedAccount", "occurred_at": "2025-12-02T05:59:59.250126407Z", "environment_id": "env_88640229614813445", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649788113519113", "identifier": "Clark", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:59:57.237447778Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.oauth_succeeded": { "post": { "summary": "Connected Account OAuth Succeeded", "description": "Triggered when OAuth authentication succeeds", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectedAccountOauthSucceededEvent" }, "example": { "spec_version": "1", "id": "evt_101649484227871236", "type": "connected_account.oauth_succeeded", "object": "ConnectedAccount", "occurred_at": "2025-12-02T05:56:53.994604757Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649474950005257", "identifier": "Bruce", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:56:52.976081699Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } }, "components": { "schemas": { "McpServiceCreateMcpSessionTokenBody": { "type": "object", "required": [ "identifier" ], "properties": { "expiry": { "description": "Optional token lifetime. Must be between 60s and 24h. Defaults to 1h when omitted.", "type": "string", "examples": [ "3600s" ] }, "identifier": { "description": "Upstream-provider identifier (typically the user's email or provider user-id) shared by the connected accounts the token represents. A single identifier can map to one connected account per connection in the MCP configuration.", "type": "string", "maxLength": 255, "minLength": 1, "examples": [ "alice@acme.com" ] } } }, "McpServiceCreateMcpConnectionSessionTokenBody": { "type": "object", "required": [ "identifier" ], "properties": { "expiry": { "description": "Token lifetime, between 60s and 24h. Defaults to 1h.", "type": "string", "examples": [ "3600s" ] }, "identifier": { "description": "Your app's ID for the user, the same value you used when the user connected.", "type": "string", "maxLength": 255, "minLength": 1, "examples": [ "user_123" ] } } }, "McpServiceListMcpConnectedAccountsBody": { "type": "object", "required": [ "identifier" ], "properties": { "identifier": { "description": "Identifier for the end user whose connected accounts to retrieve", "type": "string", "examples": [ "john.doe@example.com" ] }, "include_auth_link": { "description": "When true, generates a fresh authorization link for each connection and creates connected accounts if they do not exist. When false or omitted, returns existing connected account status without creating accounts or generating links.", "type": "boolean" } } }, "McpServiceUpdateMcpConfigBody": { "type": "object", "properties": { "connection_tool_mappings": { "description": "Updated list of connection-to-tool mappings for this MCP config. Maximum 25 entries.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/mcpMcpConfigConnectionToolMapping" } }, "description": { "description": "Updated description for the MCP configuration", "type": "string", "examples": [ "Updated daily summarizer config" ] } } }, "connected_accountsAuthorizationDetails": { "type": "object", "title": "Authentication credentials container supporting multiple auth types", "properties": { "google_dwd": { "title": "Google Domain-Wide Delegation credentials", "$ref": "#/components/schemas/connected_accountsGoogleDWDAuth" }, "oauth_token": { "title": "OAuth 2.0 credentials", "$ref": "#/components/schemas/connected_accountsOauthToken" }, "static_auth": { "title": "Static authentication credentials", "$ref": "#/components/schemas/connected_accountsStaticAuth" }, "trusted_idp": { "title": "Trusted IDP federated credentials (e.g. AWS STS temporary credentials)", "$ref": "#/components/schemas/connected_accountsTrustedIDPAuth" } } }, "connected_accountsConnectedAccount": { "type": "object", "properties": { "api_config": { "description": "Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags.", "type": "object", "examples": [ { "base_url": "https://api.custom-domain.com", "rate_limit": 1000, "timeout": 30 } ] }, "authorization_details": { "description": "The account's credentials. Set the one that matches the connection's auth type - `oauth_token`, `static_auth`, `google_dwd` or `trusted_idp`.", "$ref": "#/components/schemas/connected_accountsAuthorizationDetails" }, "authorization_type": { "description": "Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods.", "$ref": "#/components/schemas/connected_accountsConnectorType" }, "connection_id": { "description": "Reference to the parent connection configuration. Links this account to a specific connector setup in your environment.", "type": "string", "examples": [ "conn_24834495392086178" ] }, "connector": { "description": "Connector identifier (e.g., 'notion', 'slack', 'salesforce'). Indicates which third-party application this account connects to.", "type": "string", "examples": [ "notion" ] }, "id": { "description": "Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'.", "type": "string", "examples": [ "ca_24834495392086178" ] }, "identifier": { "description": "The unique identifier for this account in the third-party service. Typically an email address, user ID, or workspace identifier.", "type": "string", "examples": [ "user@example.com" ] }, "is_org_wide_credential": { "description": "Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account.", "type": "boolean" }, "last_used_at": { "description": "Timestamp when this connected account was last used to make an API call. Useful for tracking active connections.", "type": "string", "format": "date-time", "examples": [ "2024-03-20T14:30:00Z" ] }, "provider": { "description": "The app the account connects to, such as `GMAIL` or `SLACK`.", "type": "string", "examples": [ "GMAIL" ] }, "status": { "description": "Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification.", "$ref": "#/components/schemas/connected_accountsConnectorStatus" }, "token_expires_at": { "description": "Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized.", "type": "string", "format": "date-time", "examples": [ "2024-12-31T23:59:59Z" ] }, "updated_at": { "description": "Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes.", "type": "string", "format": "date-time", "examples": [ "2024-03-20T15:04:05Z" ] } } }, "connected_accountsConnectedAccountForList": { "type": "object", "title": "Connected account summary for list operations - excludes sensitive authorization details", "properties": { "authorization_type": { "description": "Authorization mechanism type.", "$ref": "#/components/schemas/connected_accountsConnectorType" }, "connection_id": { "description": "Parent connection configuration reference.", "type": "string", "examples": [ "conn_24834495392086178" ] }, "connector": { "description": "Connector identifier.", "type": "string", "examples": [ "notion" ] }, "id": { "description": "Unique connected account identifier.", "type": "string", "examples": [ "ca_24834495392086178" ] }, "identifier": { "description": "The unique identifier for this account in the third-party service.", "type": "string", "examples": [ "user@example.com" ] }, "is_org_wide_credential": { "description": "Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account.", "type": "boolean" }, "last_used_at": { "description": "Last usage timestamp.", "type": "string", "format": "date-time", "examples": [ "2024-03-20T14:30:00Z" ] }, "provider": { "description": "The app the account connects to, such as `GMAIL` or `SLACK`.", "type": "string", "examples": [ "GMAIL" ] }, "status": { "description": "Current connection status.", "$ref": "#/components/schemas/connected_accountsConnectorStatus" }, "token_expires_at": { "description": "Token expiration timestamp.", "type": "string", "format": "date-time", "examples": [ "2024-12-31T23:59:59Z" ] }, "updated_at": { "description": "Last modification timestamp.", "type": "string", "format": "date-time", "examples": [ "2024-03-20T15:04:05Z" ] } } }, "connected_accountsConnectorStatus": { "description": "- ACTIVE: Account is connected and credentials are valid\n - EXPIRED: Access token has expired and needs refresh\n - PENDING_AUTH: Account awaiting user authorization (re-auth initiated)\n - PENDING_VERIFICATION: OAuth complete; awaiting user identity verification\nbefore activation\n - DISCONNECTED: Account has been manually disconnected", "type": "string", "title": "Status of a connected account indicating its current state", "enum": [ "ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION", "DISCONNECTED" ] }, "connected_accountsConnectorType": { "description": "- OAUTH: OAuth 2.0 authorization with access and refresh tokens\n - API_KEY: Static API key authentication\n - BASIC_AUTH: HTTP Basic Authentication (username/password)\n - BEARER_TOKEN: Bearer token authentication\n - CUSTOM: Custom authentication mechanism\n - BASIC: Basic authentication (alias)\n - OAUTH_M2M: OAuth 2.0 client credentials (machine-to-machine)\n - TRELLO_OAUTH1: Trello token-based OAuth1-style browser authorization\n - GOOGLE_DWD: Google Domain-Wide Delegation\n - TRUSTED_IDP: Trusted Identity Provider federation (e.g. AWS STS AssumeRoleWithWebIdentity)\n - SMART_FHIR: SMART on FHIR (SMART App Launch) — OAuth 2.0 authorization\nfor FHIR servers\n - NO_AUTH: No authentication — connector requires no credentials (e.g. public docs MCP servers)", "type": "string", "title": "Type of authentication mechanism used for the connected account", "enum": [ "OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC", "OAUTH_M2M", "TRELLO_OAUTH1", "GOOGLE_DWD", "TRUSTED_IDP", "SMART_FHIR", "NO_AUTH" ] }, "connected_accountsCreateConnectedAccountRequest": { "type": "object", "properties": { "connected_account": { "description": "Details of the connected account to create", "$ref": "#/components/schemas/v1connected_accountsCreateConnectedAccount", "examples": [ { "authorization_details": { "oauth_token": { "access_token": "...", "refresh_token": "...", "scopes": [ "read", "write" ] } }, "authorization_type": "OAUTH2" } ] }, "connector": { "description": "Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "type": "string", "examples": [ "notion" ] }, "identifier": { "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", "type": "string", "examples": [ "user@example.com" ] }, "organization_id": { "description": "An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set.", "type": "string", "examples": [ "org_121312434123312" ] }, "user_id": { "description": "A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set.", "type": "string", "examples": [ "user_121312434123312" ] } } }, "connected_accountsCreateConnectedAccountResponse": { "type": "object", "properties": { "connected_account": { "description": "The newly created connected account with its unique identifier, status, and complete authorization details including access tokens.", "$ref": "#/components/schemas/connected_accountsConnectedAccount" } } }, "connected_accountsDeleteConnectedAccountRequest": { "type": "object", "properties": { "connector": { "description": "Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "type": "string", "examples": [ "notion" ] }, "id": { "description": "Unique identifier for the connected account to delete", "type": "string", "examples": [ "ca_123" ] }, "identifier": { "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", "type": "string", "examples": [ "user@example.com" ] }, "organization_id": { "description": "An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set.", "type": "string", "examples": [ "org_121312434123312" ] }, "user_id": { "description": "A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set.", "type": "string", "examples": [ "user_121312434123312" ] } } }, "connected_accountsGetConnectedAccountByIdentifierResponse": { "type": "object", "properties": { "connected_account": { "description": "The connected account.", "$ref": "#/components/schemas/connected_accountsConnectedAccount" } } }, "connected_accountsGetMagicLinkForConnectedAccountRequest": { "type": "object", "properties": { "connector": { "description": "Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "type": "string", "examples": [ "notion" ] }, "id": { "description": "Unique identifier for the connected account", "type": "string", "examples": [ "ca_123" ] }, "identifier": { "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", "type": "string", "examples": [ "user@example.com" ] }, "organization_id": { "description": "An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set.", "type": "string", "examples": [ "org_121312434123312" ] }, "state": { "description": "Optional opaque state value. State added to the user verify redirect URL query params to validate the user verification", "type": "string", "examples": [ "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=" ] }, "user_id": { "description": "A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set.", "type": "string", "examples": [ "user_121312434123312" ] }, "user_verify_url": { "description": "Your app's URL that Scalekit sends the user to after they approve access, to confirm they are the user your app meant. Required when the environment verifies users with a custom verifier.", "type": "string", "examples": [ "https://app.yourapp.com/user/verify/callback" ] } } }, "connected_accountsGetMagicLinkForConnectedAccountResponse": { "type": "object", "properties": { "expiry": { "description": "Expiry timestamp for the authentication link", "type": "string", "format": "date-time", "examples": [ "2024-03-20T15:04:05Z" ] }, "link": { "description": "The one-time link to send the user to. It opens the app's consent screen, or a form for their credentials.", "type": "string", "examples": [ "https://notion.com/oauth/authorize?client_id=..." ] } } }, "connected_accountsGoogleDWDAuth": { "description": "Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections.\nSend only subject in requests; access_token, scopes, and token_expires_at are response-only.", "type": "object", "properties": { "access_token": { "description": "OAuth access token acquired via the jwt-bearer grant. Present in responses only.", "type": "string", "readOnly": true, "examples": [ "ya29.a0AfH6SMBx..." ] }, "scopes": { "description": "OAuth scopes granted to this token. Present in responses only.", "type": "array", "items": { "type": "string" }, "readOnly": true, "examples": [ [ "openid", "https://www.googleapis.com/auth/userinfo.email" ] ] }, "subject": { "description": "Email address of the Google Workspace user to impersonate via Domain-Wide Delegation.", "type": "string", "examples": [ "user@example.com" ] }, "token_expires_at": { "description": "When the access token expires. Present in responses only.", "type": "string", "format": "date-time", "readOnly": true } } }, "connected_accountsListConnectedAccountsResponse": { "type": "object", "properties": { "connected_accounts": { "description": "List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/connected_accountsConnectedAccountForList" } }, "next_page_token": { "description": "Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page_token in the next request.", "type": "string", "examples": [ "eyJvZmZzZXQiOjIwfQ==" ] }, "prev_page_token": { "description": "Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page_token to go back.", "type": "string", "examples": [ "eyJvZmZzZXQiOjB9" ] }, "total_size": { "description": "Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination.", "type": "integer", "format": "int64", "examples": [ 100 ] } } }, "connected_accountsOauthToken": { "type": "object", "title": "OAuth 2.0 access and refresh tokens with scopes", "properties": { "access_token": { "description": "OAuth access token for API requests. Typically short-lived and must be refreshed after expiration.", "type": "string", "examples": [ "ya29.a0AfH6SMBx..." ] }, "domain": { "description": "Associated domain for workspace or organization-scoped OAuth connections (e.g., Google Workspace domain).", "type": "string", "examples": [ "example.com" ] }, "refresh_token": { "description": "OAuth refresh token for obtaining new access tokens. Long-lived and used to maintain persistent authorization.", "type": "string", "examples": [ "1//0gHJxZ-Lb2..." ] }, "scopes": { "description": "List of granted OAuth scopes defining the permissions and access levels for this connection.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/userinfo.email" ] ] } } }, "connected_accountsSearchConnectedAccountsResponse": { "type": "object", "properties": { "connected_accounts": { "description": "List of connected accounts matching the search query. Excludes sensitive authorization details.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/connected_accountsConnectedAccountForList" } }, "next_page_token": { "description": "Pagination token for the next page. Empty if this is the last page.", "type": "string", "examples": [ "eyJvZmZzZXQiOjMwfQ==" ] }, "prev_page_token": { "description": "Pagination token for the previous page. Empty if this is the first page.", "type": "string", "examples": [ "eyJvZmZzZXQiOjB9" ] }, "total_size": { "description": "Total count of accounts matching the search query across all pages.", "type": "integer", "format": "int64", "examples": [ 100 ] } } }, "connected_accountsStaticAuth": { "type": "object", "title": "Static authentication credentials for API keys, bearer tokens, or basic auth", "properties": { "details": { "description": "Flexible JSON structure containing static credentials. Format varies by connector type (API key, username/password, etc.).", "type": "object", "examples": [ { "api_key": "sk_live_...", "api_secret": "..." } ] } } }, "connected_accountsTrustedIDPAuth": { "description": "Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only `db_user`. Responses include `access_key_id` and `expiry`, never the secret key or session token.", "type": "object", "properties": { "access_key_id": { "description": "Federated access key ID issued by the trusted identity provider. Present in responses only.", "type": "string", "readOnly": true, "examples": [ "ASIA..." ] }, "db_user": { "description": "Target database user for the federated session (required for provisioned Redshift clusters; ignored for serverless workgroups).", "type": "string", "examples": [ "analytics_reader" ] }, "expiry": { "description": "When the federated credentials expire. Present in responses only.", "type": "string", "format": "date-time", "readOnly": true }, "secret_access_key": { "description": "Federated secret access key. Never returned in public API responses.", "type": "string", "readOnly": true }, "session_token": { "description": "Federated session token. Never returned in public API responses.", "type": "string", "readOnly": true } } }, "connected_accountsUpdateConnectedAccountRequest": { "type": "object", "properties": { "connected_account": { "description": "Details of the connected account to update", "$ref": "#/components/schemas/v1connected_accountsUpdateConnectedAccount", "examples": [ { "authorization_details": { "oauth_token": { "access_token": "...", "refresh_token": "...", "scopes": [ "read", "write" ] } }, "authorization_type": "OAUTH2" } ] }, "connector": { "description": "Connector identifier (e.g., 'notion', 'slack', 'google'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed.", "type": "string", "examples": [ "notion" ] }, "id": { "description": "Unique identifier for the connected account to update", "type": "string", "examples": [ "ca_123" ] }, "identifier": { "description": "The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier).", "type": "string", "examples": [ "user@example.com" ] }, "organization_id": { "description": "An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set.", "type": "string", "examples": [ "org_121312434123312" ] }, "user_id": { "description": "A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set.", "type": "string", "examples": [ "user_121312434123312" ] } } }, "connected_accountsUpdateConnectedAccountResponse": { "type": "object", "properties": { "connected_account": { "description": "The updated connected account with refreshed credentials, new token expiry, and modified configuration settings.", "$ref": "#/components/schemas/connected_accountsConnectedAccount" } } }, "connected_accountsVerifyConnectedAccountUserRequest": { "type": "object", "required": [ "auth_request_id", "identifier" ], "properties": { "auth_request_id": { "description": "Auth request ID as base64url-encoded opaque token from the user verify redirect URL query params", "type": "string", "examples": [ "QVNDSUFyY2hhYml0dGVyXzE2ODQ5NzIwNzI0NTY=" ] }, "identifier": { "description": "Current logged in user's connected account identifier", "type": "string", "examples": [ "user@example.com" ] } } }, "connected_accountsVerifyConnectedAccountUserResponse": { "type": "object", "properties": { "post_user_verify_redirect_url": { "description": "URL to redirect the user to after successful verification", "type": "string", "examples": [ "https://env1.example.com/connect/success" ] } } }, "mcpCreateMcpConfigResponse": { "type": "object", "properties": { "config": { "description": "The created MCP configuration", "$ref": "#/components/schemas/mcpMcpConfig" } } }, "mcpCreateMcpSessionTokenResponse": { "type": "object", "properties": { "expires_at": { "description": "Absolute time at which the token expires. Equals issued_at + expiry.", "type": "string", "format": "date-time", "readOnly": true }, "token": { "description": "Signed JWT (RS256) whose `sub` claim is the supplied identifier and whose `aud` claim is the MCP server URL the token is scoped to: the MCP configuration's server URL for a configuration token, or the connection's `/mcp/v3/connections/{key_id}` URL for a connection token. A configuration token also carries the MCP configuration ID (`mcp_cfg`); a connection token carries the connection ID (`conn_id`) instead. Both carry the resolved connected-account IDs (`ca_ids`). Signed with the calling environment's active JWT signing key.", "type": "string", "readOnly": true, "examples": [ "eyJhbGciOiJSUzI1NiIsImtpZCI6InNua18xMjMifQ.eyJhdWQiOlsiYWxpY2VAYWNtZS5jb20iXSwidG9rZW5fdHlwZSI6Im1jcF9zZXNzaW9uIn0.signature" ] } } }, "mcpGetMcpConfigResponse": { "type": "object", "properties": { "config": { "description": "The requested MCP configuration", "$ref": "#/components/schemas/mcpMcpConfig" } } }, "mcpListMcpConfigsResponse": { "type": "object", "properties": { "configs": { "description": "List of MCP configurations", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/mcpMcpConfig" } }, "next_page_token": { "description": "Pagination token to fetch the next page", "type": "string" }, "prev_page_token": { "description": "Pagination token to fetch the previous page", "type": "string" }, "total_size": { "description": "Total number of configs matching the filter", "type": "integer", "format": "int64" } } }, "mcpListMcpConnectedAccountsResponse": { "type": "object", "properties": { "connected_accounts": { "description": "Connected account state for each connection in the configuration", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/mcpMcpConnectionAuthState" } } } }, "mcpMcpConfig": { "type": "object", "properties": { "connection_tool_mappings": { "description": "List of connection-to-tool mappings for this MCP config. Maximum 25 entries.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/mcpMcpConfigConnectionToolMapping" } }, "description": { "description": "Description of the MCP configuration", "type": "string", "examples": [ "Summarizes daily emails and posts to Slack" ] }, "id": { "description": "Unique ID of the MCP config", "type": "string", "readOnly": true, "examples": [ "cfg_85630864460904897" ] }, "mcp_server_url": { "description": "The URL MCP clients connect to for this server. Every user and session shares it; the session token identifies the user.", "type": "string", "readOnly": true, "examples": [ "https://env.scalekit.com/mcp/v3/servers/550e8400-e29b-41d4-a716-446655440000" ] }, "name": { "description": "Unique name for the MCP configuration. Must be 1–100 characters. Allowed characters: lowercase letters (a–z), digits (0–9), hyphens (-), and underscores (_).", "type": "string", "maxLength": 100, "minLength": 1, "examples": [ "daily-summarizer" ] } } }, "mcpMcpConfigConnectionToolMapping": { "type": "object", "properties": { "connected_account_id": { "description": "Connected account backing this connection in the MCP instance context", "type": "string", "readOnly": true }, "connected_account_status": { "description": "Authentication status for the connected account", "type": "string", "readOnly": true }, "connection_id": { "description": "Unique ID of the connection", "type": "string", "readOnly": true }, "connection_name": { "description": "Developer-assigned connection name", "type": "string" }, "provider": { "description": "Provider name for this connection", "type": "string", "readOnly": true }, "tools": { "description": "List of tool names linked to this connection (empty = all tools)", "type": "array", "items": { "type": "string" } } } }, "mcpMcpConnectionAuthState": { "type": "object", "properties": { "authentication_link": { "description": "Fresh authorization link for the connected account. Empty when include_auth_link is false or when the connection has no associated key.", "type": "string" }, "connected_account_id": { "description": "ID of the connected account for this user and connection", "type": "string" }, "connected_account_status": { "description": "Authentication status of the connected account", "type": "string" }, "connection_id": { "description": "ID of the connection", "type": "string" }, "connection_name": { "description": "Name of the connection", "type": "string" }, "provider": { "description": "Provider identifier for the connection", "type": "string" } } }, "mcpUpdateMcpConfigResponse": { "type": "object", "properties": { "config": { "description": "The updated MCP configuration", "$ref": "#/components/schemas/mcpMcpConfig" } } }, "providersCreateProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/providersProvider" } } }, "providersDeleteProviderResponse": { "type": "object" }, "providersProvider": { "type": "object", "title": "Provider represents a connected app provider", "properties": { "auth_patterns": { "type": "array", "items": { "type": "object" } }, "categories": { "type": "array", "items": { "type": "string" } }, "coming_soon": { "type": "boolean" }, "description": { "type": "string" }, "display_name": { "type": "string" }, "display_priority": { "type": "integer", "format": "int32" }, "icon_src": { "type": "string" }, "id": { "type": "string" }, "identifier": { "type": "string" }, "is_custom": { "description": "Indicates whether the provider is environment-scoped (custom provider)", "type": "boolean", "examples": [ false ] }, "is_custom_mcp": { "description": "Indicates whether this is an environment-scoped MCP-based custom provider", "type": "boolean", "examples": [ false ] }, "metadata": { "description": "Custom key-value metadata stored for this provider. Returned for all providers; defaults to {} when no metadata has been set.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "api_version": "v2", "region": "us-east-1" } ] }, "proxy_enabled": { "type": "boolean" }, "proxy_url": { "type": "string" } } }, "providersUpdateProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/providersProvider" } } }, "toolsExecuteToolRequest": { "type": "object", "properties": { "agent_run_id": { "description": "Optional. Customer-supplied identifier grouping multiple tool calls into a single agent run. Useful for correlating logs across an agentic workflow.", "type": "string", "examples": [ "run_abc123" ] }, "connected_account_id": { "description": "Optional. The unique ID of the connected account. Use this to directly identify the connected account instead of using identifier + connector combination.", "type": "string", "examples": [ "ca_123" ] }, "connector": { "description": "Optional. The name of the connector/provider (e.g., 'Google Workspace', 'Slack', 'Notion'). Alphanumeric characters, spaces, hyphens, underscores, and colons are allowed. Use this in combination with identifier to identify the connected account.", "type": "string", "examples": [ "Google Workspace" ] }, "identifier": { "description": "Optional. The unique identifier for the connected account within the third-party service (e.g., email address, user ID, workspace identifier). Use this in combination with connector to identify the connected account.", "type": "string", "examples": [ "user@example.com" ] }, "organization_id": { "description": "Optional. The organization ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple organizations.", "type": "string", "examples": [ "org_123" ] }, "params": { "description": "JSON object containing the parameters required for tool execution. The structure depends on the specific tool being executed.", "type": "object", "examples": [ { "body": "Hello World", "subject": "Hello", "to": "user@example.com" } ] }, "tool_name": { "description": "Name of the tool to execute", "type": "string", "examples": [ "send_email" ] }, "user_id": { "description": "Optional. The user ID to scope the connected account lookup. Use this to narrow down the search when the same identifier exists across multiple users.", "type": "string", "examples": [ "user_123" ] } } }, "toolsExecuteToolResponse": { "type": "object", "properties": { "data": { "description": "The tool's output: the app's response, as JSON.", "type": "object", "examples": [ { "body": "Hello World", "subject": "Hello", "to": "user@example.com" } ] }, "execution_id": { "description": "Unique identifier for the tool execution", "type": "string", "examples": [ "123456789" ] } } }, "toolsListAvailableToolsResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for fetching the next page of tools", "type": "string", "examples": [ "eyJwYWdlIjozLCJsaW1pdCI6MzB9" ] }, "prev_page_token": { "description": "Token for fetching the previous page of tools", "type": "string", "examples": [ "eyJwYWdlIjoxLCJsaW1pdCI6MzB9" ] }, "tools": { "description": "List of tools available for the identifier", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/toolsTool" } }, "total_size": { "description": "Total number of available tools matching the query", "type": "integer", "format": "int64", "examples": [ 104 ] } } }, "toolsListScopedToolsResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for fetching the next page of tools", "type": "string", "examples": [ "eyJwYWdlIjozLCJsaW1pdCI6MzB9" ] }, "prev_page_token": { "description": "Token for fetching the previous page of tools", "type": "string", "examples": [ "eyJwYWdlIjoxLCJsaW1pdCI6MzB9" ] }, "tools": { "description": "List of tools scoped to the given connected account identifier", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/toolsScopedTool" } }, "total_size": { "description": "Total number of tools matching the query", "type": "integer", "format": "int64", "examples": [ 104 ] } } }, "toolsListToolsResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for fetching the next page of tools", "type": "string", "examples": [ "eyJwYWdlIjozLCJsaW1pdCI6MzB9" ] }, "prev_page_token": { "description": "Token for fetching the previous page of tools", "type": "string", "examples": [ "eyJwYWdlIjoxLCJsaW1pdCI6MzB9" ] }, "tool_names": { "description": "List of tool names, returned when filter.summary is true", "type": "array", "items": { "type": "string" }, "examples": [ [ "gmail_send_message" ] ] }, "tools": { "description": "List of tools, returned when filter.summary is false or omitted", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/toolsTool" } }, "total_size": { "description": "Total number of tools matching the query", "type": "integer", "format": "int64", "examples": [ 104 ] } } }, "toolsScopedTool": { "type": "object", "properties": { "connected_account_id": { "description": "ID of the connected account for this scoped tool", "type": "string", "examples": [ "ca_123" ] }, "identifier": { "description": "Connected account identifier this tool is scoped to", "type": "string" }, "tool": { "description": "The underlying tool definition", "$ref": "#/components/schemas/toolsTool" } } }, "toolsSearchedTool": { "type": "object", "properties": { "connections": { "description": "Connections for this tool's provider that the supplied identifier has a connected account for (any status), each with its own readiness state and connected_account_id. Populated only when identifier is supplied in the request. An empty array means this identifier does not have any connection at all for this tool's provider -- not an error, and not the same as a connection listed with TOOL_READINESS_STATE_NEEDS_CONNECTION. More than one entry means the identifier has accounts on multiple connections for this provider (e.g. two Slack workspaces) -- inspect each entry's own readiness_state before using its connected_account_id.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/toolsConnectionReadiness" } }, "description": { "description": "Human-readable description of what the tool does", "type": "string", "examples": [ "Send a message to a Slack channel or user" ] }, "name": { "description": "Fully qualified tool name to pass to ExecuteTool", "type": "string", "examples": [ "slack_send_message" ] }, "provider": { "description": "Provider the tool belongs to", "type": "string", "examples": [ "SLACK" ] }, "score": { "description": "Relevance score for this result. Higher is better; comparable only within a single response.", "type": "number", "format": "double", "examples": [ 0.82 ] } } }, "toolsConnectionReadiness": { "type": "object", "properties": { "connected_account_id": { "description": "ID of the connected account for this connection and the supplied identifier. Always populated when this entry is present, regardless of readiness_state -- check readiness_state before using it, since only TOOL_READINESS_STATE_READY means it is safe to pass to ExecuteTool now.", "type": "string", "examples": [ "ca_123" ] }, "connection_name": { "description": "Name of this connection.", "type": "string", "examples": [ "Acme Slack" ] }, "readiness_state": { "description": "Whether this specific connection is usable right now for the supplied identifier, independent of every other connection listed for this provider.", "$ref": "#/components/schemas/toolsToolReadinessState", "examples": [ "TOOL_READINESS_STATE_READY" ] } } }, "toolsToolReadinessState": { "description": "Readiness of a connection for use with ExecuteTool.\n\n - TOOL_READINESS_STATE_READY: Usable now. Safe to pass connected_account_id to ExecuteTool.\n - TOOL_READINESS_STATE_NEEDS_CONNECTION: A connected account exists for this connection but is inactive (e.g. disconnected). The end user must re-establish the connection.\n - TOOL_READINESS_STATE_NEEDS_REAUTH: A connected account exists but its token expired. The end user must re-authenticate.", "type": "string", "enum": [ "TOOL_READINESS_STATE_READY", "TOOL_READINESS_STATE_NEEDS_CONNECTION", "TOOL_READINESS_STATE_NEEDS_REAUTH" ] }, "toolsSearchToolsRequest": { "type": "object", "properties": { "identifier": { "description": "Optional connected-account identifier (e.g. the end user's email or ID). When set, each result is annotated with a readiness state for this identifier's connections. When omitted, results are ranked without readiness annotation.", "type": "string", "examples": [ "user@example.com" ] }, "query": { "description": "Natural-language query or keywords describing the job to be done. Ranked against tool names, descriptions, and providers. 1-256 characters.", "type": "string", "examples": [ "send a message to a slack channel" ] }, "top_k": { "description": "Maximum number of ranked results to return. Defaults to 10, capped at 50.", "type": "integer", "format": "int64", "examples": [ 10 ] } }, "required": [ "query" ] }, "toolsSearchToolsResponse": { "type": "object", "properties": { "tools": { "description": "Tools matching the query, ordered by descending relevance score", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/toolsSearchedTool" } } } }, "toolsTool": { "type": "object", "properties": { "definition": { "description": "Tool definition in structured format", "type": "object", "examples": [ { "input": { "type": "object" } } ] }, "id": { "description": "Unique ID of the tool. Immutable and read-only.", "type": "string", "readOnly": true, "examples": [ "tol_123" ] }, "is_default": { "description": "Marks this tool as the default version for the combination. Read-only.", "type": "boolean", "readOnly": true, "examples": [ true ] }, "metadata": { "description": "Additional metadata about the tool", "type": "object", "examples": [ { "category": "email" } ] }, "provider": { "description": "Provider name (e.g. GOOGLE). Read-only.", "type": "string", "readOnly": true, "examples": [ "GOOGLE" ] }, "tags": { "description": "Tags for categorization or filtering", "type": "array", "items": { "type": "string" }, "examples": [ [ "notification", "email" ] ] }, "updated_at": { "description": "Timestamp when the tool was last updated. Read-only.", "type": "string", "format": "date-time", "readOnly": true, "examples": [ "2023-10-01T12:00:00Z" ] } } }, "v1connected_accountsCreateConnectedAccount": { "type": "object", "title": "Payload for creating a new connected account - authorization details are optional", "properties": { "api_config": { "description": "Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags.", "type": "object", "examples": [ { "base_url": "https://api.custom-domain.com", "rate_limit": 1000, "timeout": 30 } ] }, "authorization_details": { "description": "Optional authentication credentials for the connected account. Include OAuth tokens (access_token, refresh_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update.", "$ref": "#/components/schemas/connected_accountsAuthorizationDetails", "examples": [ { "oauth_token": { "access_token": "ya29.a0...", "refresh_token": "1//0g...", "scopes": [ "email", "profile" ] } } ] } } }, "v1connected_accountsUpdateConnectedAccount": { "type": "object", "title": "Payload for updating an existing connected account - all fields optional", "properties": { "api_config": { "description": "Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified.", "type": "object", "examples": [ { "rate_limit": 2000, "timeout": 60 } ] }, "authorization_details": { "description": "Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified.", "$ref": "#/components/schemas/connected_accountsAuthorizationDetails", "examples": [ { "oauth_token": { "access_token": "ya29.new_token...", "refresh_token": "1//0g...", "scopes": [ "email", "profile", "calendar" ] } } ] } } }, "v1providersCreateCustomProvider": { "type": "object", "properties": { "auth_patterns": { "description": "Authentication patterns for the connected app provider", "type": "array", "items": { "type": "object" } }, "description": { "description": "Description of the connected app provider", "type": "string", "examples": [ "Connect to Google Workspace for email and calendar integration" ] }, "display_name": { "description": "Display name for the connected app provider", "type": "string", "examples": [ "Google Workspace" ] }, "icon_src": { "description": "URL for the provider icon. Should be an SVG image sized 800x800 pixels for best rendering experience.", "type": "string", "examples": [ "https://example.com/images/my-connector.svg" ] }, "metadata": { "description": "Custom key-value metadata for this provider. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "api_version": "v2", "region": "us-east-1" } ] }, "proxy_enabled": { "description": "This flag indicates whether proxying is turned on for the connected app provider. When enabled, requests are routed through the provider proxy instead of being sent directly.", "type": "boolean", "examples": [ true ] }, "proxy_url": { "description": "Proxy URL for the connected app provider. Must start with https://", "type": "string", "examples": [ "https://mcp.example.com/mcp" ] } } }, "v1providersUpdateCustomProvider": { "type": "object", "properties": { "auth_patterns": { "description": "Authentication patterns for the connected app provider", "type": "array", "items": { "type": "object" } }, "description": { "description": "Description of the connected app provider", "type": "string", "examples": [ "Connect to Google Workspace for email and calendar integration" ] }, "display_name": { "description": "Display name for the connected app provider", "type": "string", "examples": [ "Google Workspace" ] }, "icon_src": { "description": "URL for the provider icon. Should be an SVG image sized 800x800 pixels for best rendering experience.", "type": "string", "examples": [ "https://example.com/images/my-connector.svg" ] }, "metadata": { "description": "Custom key-value metadata for this provider. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "api_version": "v2", "region": "us-east-1" } ] }, "proxy_enabled": { "description": "This flag indicates whether proxying is turned on for the connected app provider. When enabled, requests are routed through the provider proxy instead of being sent directly.", "type": "boolean", "examples": [ true ] }, "proxy_url": { "description": "Proxy URL for the connected app provider. Must start with https://", "type": "string", "examples": [ "https://mcp.example.com/mcp" ] } } }, "ConnectedAccountStatusUpdatedEvent": { "type": "object", "description": "Payload delivered for the connected_account.status_updated webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "example": "evt_101652975398683158", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.status_updated" ], "example": "connected_account.status_updated" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2025-12-02T06:31:34.895815554Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_88640229614813449", "description": "The environment ID where the event occurred", "minLength": 1, "maxLength": 32 }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountStatusUpdatedEventData" } } }, "ConnectedAccountStatusUpdatedEventData": { "type": "object", "description": "The connected account whose status changed, including its previous status.", "required": [ "id", "identifier", "connection_id", "provider", "authorization_type", "status", "old_status" ], "properties": { "id": { "type": "string", "pattern": "^ca_", "example": "ca_133400349586228019", "description": "Unique identifier of the connected account (prefixed with \"ca_\")" }, "identifier": { "type": "string", "example": "user_123", "description": "The end-user identifier the connected account belongs to" }, "connection_id": { "type": "string", "pattern": "^conn_", "example": "conn_133400101014995480", "description": "Identifier of the connection (prefixed with \"conn_\")" }, "connection_name": { "type": "string", "example": "gmail", "description": "The connection's name, as shown in AgentKit > Connections. Omitted when it cannot be resolved." }, "provider": { "type": "string", "example": "GMAIL", "description": "The provider of the connected account" }, "authorization_type": { "type": "string", "enum": [ "OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC", "OAUTH_M2M", "TRELLO_OAUTH1", "GOOGLE_DWD", "TRUSTED_IDP", "SMART_FHIR", "NO_AUTH" ], "example": "OAUTH", "description": "The authorization type of the connected account" }, "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION", "DISCONNECTED" ], "example": "EXPIRED", "description": "The new status of the connected account" }, "old_status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION", "DISCONNECTED" ], "example": "ACTIVE", "description": "The previous status of the connected account" } } }, "ConnectedAccountEventData": { "type": "object", "description": "The connected account the event is about.", "required": [ "id", "identifier", "connection_id", "provider", "status" ], "properties": { "id": { "type": "string", "pattern": "^ca_", "example": "ca_101531404000559370", "description": "Connected account identifier" }, "identifier": { "type": "string", "example": "user_123", "description": "End-user identifier for the connected account" }, "connection_id": { "type": "string", "pattern": "^conn_", "example": "conn_100668583155073286", "description": "Connection identifier" }, "connection_name": { "type": "string", "example": "gmail", "description": "The connection's name, as shown in AgentKit > Connections. Omitted when it can't be resolved." }, "provider": { "type": "string", "example": "GMAIL", "description": "Provider of the connected account" }, "authorization_type": { "type": "string", "enum": [ "OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC", "OAUTH_M2M", "TRELLO_OAUTH1", "GOOGLE_DWD", "TRUSTED_IDP", "SMART_FHIR", "NO_AUTH" ], "example": "OAUTH", "description": "Authorization type of the connected account" }, "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION", "DISCONNECTED" ], "example": "ACTIVE", "description": "Current connected account status" }, "token_expires_at": { "type": "string", "format": "date-time", "example": "2025-12-02T06:59:57.237447Z", "description": "When the access token expires, if known" }, "last_used_at": { "type": "string", "format": "date-time", "example": "2025-12-02T06:00:01.374253Z", "description": "When the connected account was last used" } } }, "ConnectedAccountCreatedEvent": { "type": "object", "description": "Payload delivered for the connected_account.created webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.created" ], "example": "connected_account.created" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountUpdatedEvent": { "type": "object", "description": "Payload delivered for the connected_account.updated webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.updated" ], "example": "connected_account.updated" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountDeletedEvent": { "type": "object", "description": "Payload delivered for the connected_account.deleted webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.deleted" ], "example": "connected_account.deleted" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountMagicLinkGeneratedEvent": { "type": "object", "description": "Payload delivered for the connected_account.magic_link_generated webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.magic_link_generated" ], "example": "connected_account.magic_link_generated" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountOauthTokensFetchedEvent": { "type": "object", "description": "Payload delivered for the connected_account.oauth_tokens_fetched webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.oauth_tokens_fetched" ], "example": "connected_account.oauth_tokens_fetched" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountTokenRefreshSucceededEvent": { "type": "object", "description": "Payload delivered for the connected_account.token_refresh_succeeded webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.token_refresh_succeeded" ], "example": "connected_account.token_refresh_succeeded" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountTokenRefreshFailedEvent": { "type": "object", "description": "Payload delivered for the connected_account.token_refresh_failed webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.token_refresh_failed" ], "example": "connected_account.token_refresh_failed" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } }, "ConnectedAccountOauthSucceededEvent": { "type": "object", "description": "Payload delivered for the connected_account.oauth_succeeded webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "object", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "connected_account.oauth_succeeded" ], "example": "connected_account.oauth_succeeded" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)" }, "environment_id": { "type": "string", "pattern": "^env_", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization ID (if applicable)" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "ConnectedAccount" ], "example": "ConnectedAccount" }, "data": { "$ref": "#/components/schemas/ConnectedAccountEventData" }, "display_name": { "type": "string", "description": "Human-readable display name for the event" } } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://$SCALEKIT_ENVIRONMENT_URL/oauth/token", "scopes": { "": "No scope required for client credentials flow" } } } } } }, "x-scalar-environments": { "production": { "variables": { "SCALEKIT_ENVIRONMENT_URL": { "default": "https://$SCALEKIT_ENVIRONMENT_URL", "description": "yourapp.scalekit.com" } } }, "staging": { "variables": { "SCALEKIT_ENVIRONMENT_URL": { "default": "https://$SCALEKIT_ENVIRONMENT_URL", "description": "yourapp.scalekit.dev" } } } }, "x-scalar-active-environment": "staging", "x-scalekit-docs-operation-rank": { "default": 0, "path-segments": [ { "match": ":external", "rank": 1 }, { "match": ":search", "rank": 2 } ] } }