{ "openapi": "3.1.1", "info": { "description": "# Overview\n\nThe Scalekit API is a RESTful API that covers both **AgentKit** (AI-agent OAuth, tool calling, connected accounts) and **SaaSKit** (organizations, users, SSO, directory sync, RBAC, sessions).\n\nAll requests must use HTTPS. All API requests use the following base URLs:\n\n```\nhttps://{your-subdomain}.scalekit.dev (Development)\nhttps://{your-subdomain}.scalekit.com (Production)\nhttps://auth.yourapp.com (Custom domain)\n```\n\n## Authentication\n\nScalekit uses OAuth 2.0 Client Credentials for API authentication.\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## Product-specific references\n\n- [AgentKit APIs](https://docs.scalekit.com/agentkit/reference/) — Connected accounts, connectors, tool calling, MCP configurations\n- [SaaSKit APIs](https://docs.scalekit.com/saaskit/apis/) — Organizations, users, SSO, directory sync, RBAC, sessions\n", "title": "Scalekit API Reference", "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": "Organizations", "description": "Manage organizations (tenants), settings, and organization-scoped resources." }, { "name": "Permissions", "description": "Define and manage permissions for role-based access control." }, { "name": "Users", "description": "User lifecycle, memberships, invitations, and profile management." }, { "name": "Connections", "description": "Enterprise SSO connections (SAML/OIDC) for organizations." }, { "name": "Directory", "description": "Directory sync (SCIM) for provisioning users and groups." }, { "name": "Roles", "description": "Organization and environment roles for RBAC." }, { "name": "Sessions", "description": "Session policies and session management." }, { "name": "Authentication Logs", "description": "Authentication request audit logs for login activity and troubleshooting." }, { "name": "Domains", "description": "Organization domains and domain verification." }, { "name": "API Auth", "description": "Machine-to-machine clients, API keys, and client credentials." }, { "name": "Magic link & OTP", "description": "Passwordless authentication with magic links and one-time codes." }, { "name": "Passkeys", "description": "WebAuthn / passkey authentication." }, { "name": "Connected Accounts", "description": "Authenticated third-party accounts for AI agents and tool calling." }, { "name": "Connectors", "description": "Built-in and custom connectors (providers) for third-party services." }, { "name": "Tool Calling", "description": "Execute tools on behalf of a connected account." }, { "name": "MCP Configurations", "description": "Reusable MCP configurations that map connections and tools to an MCP server." } ], "externalDocs": { "description": "Scalekit Docs", "url": "https://docs.scalekit.com/" }, "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/agentkit/connection": { "get": { "description": "Lists the connections in the environment, newest first, without their settings. Filter by connector, or search by name. Use it to find a connection's name or ID, or to check whether a connector already has a connection; call [Get a connection](/agentkit/reference/connections/get-a-connection/) for one connection's settings.", "tags": [ "App Connections" ], "summary": "List connections", "operationId": "ConnectionService_ListAppConnectionSummaries", "parameters": [ { "schema": { "type": "integer", "format": "int64" }, "description": "The number of connections to return, up to 100. Defaults to 10.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "The `next_page_token` from the previous response, to get the next page. Leave it out for the first page.", "name": "page_token", "in": "query" }, { "schema": { "type": "string" }, "description": "Return only connections for this connector, by its identifier, such as `GMAIL`. A connection's `provider` field holds the same value.", "name": "provider", "in": "query" }, { "schema": { "type": "string" }, "description": "Return connections whose name, connector or connector display name contains this text, such as `gmail`. At least 3 characters.", "name": "query", "in": "query" } ], "responses": { "200": { "description": "The connections on this page, with the token for the next page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsListAppConnectionSummariesResponse" } } } }, "400": { "description": "Invalid request - for example, `query` is shorter than 3 characters.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } } }, "post": { "description": "Creates a connection for a connector, such as Gmail. The connection's type comes from the connector, and an OAuth connection starts with the connector's endpoints and default scopes.\n\nNext, register an OAuth app with the provider using the `redirect_uri` from the response, then add its client ID, client secret and the scopes you need with [Update a connection](/agentkit/reference/connections/update-a-connection/).", "tags": [ "App Connections" ], "summary": "Create a connection", "operationId": "ConnectionService_CreateAppConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1connectionsCreateAppConnection" } } }, "required": true }, "responses": { "200": { "description": "The connection that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsCreateAppConnectionResponse" } } } }, "400": { "description": "Invalid request - the connector is missing or unknown, or the connection name is already used or reserved. Error code `DUPLICATE_IDENTIFIER` when the name is already used.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/agentkit/connection/{connection_identifier}": { "get": { "description": "Returns a connection with its settings, looked up by its name or its ID. Use it to check the scopes the connection requests, or to copy its `redirect_uri` into the app you registered with the provider. Secrets come back masked.", "tags": [ "App Connections" ], "summary": "Get a connection", "operationId": "ConnectionService_GetAppConnection", "parameters": [ { "schema": { "type": "string" }, "description": "The connection's name, such as `gmail-work`, or its ID, such as `conn_70219645518265104`. Both are in the [List connections](/agentkit/reference/connections/list-connections/) response.", "name": "connection_identifier", "in": "path", "required": true } ], "responses": { "200": { "description": "The connection and its settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsGetAppConnectionResponse" } } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no connection with this name or ID. Error code `RESOURCE_NOT_FOUND`.", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/agentkit/connection/{connection_id}": { "patch": { "description": "Changes a connection's name or settings. Send only the fields you want to change; everything else keeps its current value, including the stored client secret. To clear a list or a map, send it empty (`[]` or `{}`).\n\nTo see the current settings first, call [Get a connection](/agentkit/reference/connections/get-a-connection/). Sending your own `client_id` or `client_secret` switches the connection to your credentials, unless you also set `use_scalekit_creds`.", "tags": [ "App Connections" ], "summary": "Update a connection", "operationId": "ConnectionService_UpdateAppConnection", "parameters": [ { "schema": { "type": "string" }, "description": "The connection's ID, such as `conn_70219645518265104`. Use the ID, not the name. Find it in the `id` field of the [Create](/agentkit/reference/connections/create-a-connection/), [Get](/agentkit/reference/connections/get-a-connection/) or [List connections](/agentkit/reference/connections/list-connections/) response.", "name": "connection_id", "in": "path", "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsAppConnectionUpdate" } } }, "required": true }, "responses": { "200": { "description": "The connection with its new settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsUpdateAppConnectionResponse" } } } }, "400": { "description": "Invalid request - for example, an unknown field, a name that is already used, settings that don't match the connection's type, `required_scopes` that aren't all in `scopes`, or `use_scalekit_creds` on a connector that doesn't offer Scalekit credentials.", "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 ID. Error code `RESOURCE_NOT_FOUND`.", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connections/{connection_id}": { "delete": { "description": "Deletes a connection. It fails while connected accounts or Virtual MCP servers still use the connection. Delete its connected accounts first with [Delete a connected account](/agentkit/reference/connected-accounts/delete-a-connected-account/), and remove it from each server with [Update a Virtual MCP server](/agentkit/reference/virtual-mcp-servers/update-a-virtual-mcp-server/).", "tags": [ "App Connections" ], "summary": "Delete a connection", "operationId": "ConnectionService_DeleteEnvironmentConnection", "parameters": [ { "schema": { "type": "string" }, "description": "The connection's ID, such as `conn_70219645518265104`. Find it in the `id` field of the [List connections](/agentkit/reference/connections/list-connections/) response.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The connection was deleted." }, "400": { "description": "Invalid request - connected accounts or Virtual MCP servers still use the connection.", "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 ID. Error code `RESOURCE_NOT_FOUND`.", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connections": { "get": { "description": "Retrieves a list of connections in the environment", "tags": [ "Connections" ], "summary": "List connections", "operationId": "ConnectionService_ListConnections", "parameters": [ { "schema": { "type": "string" }, "description": "Filter connections by organization identifier", "name": "organization_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter connections by email domain associated with the organization", "name": "domain", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter connections by status. Use 'all' to include all connections regardless of status. Default behavior shows only active (completed and enabled) connections", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved connections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsListConnectionsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// List connections by organization id\nconst connections = await scalekit.connection.listConnections(organizationId)\n\n// List connections by domain\nconst connections = await scalekit.connection.listConnectionsByDomain(domain)" }, { "label": "Python SDK", "lang": "python", "source": "# List connections by organization id\nconnections = scalekit_client.connection.list_connections(\n organization_id\n)\n\n# List connections by domain\nresponse = scalekit_client.connection.list_connections_by_domain(domain=\"example.com\")" }, { "label": "Go SDK", "lang": "go", "source": "// List connections by organization id\nconnections, err := scalekitClient.Connection().ListConnections(\n ctx,\n organizationId\n)\n\n// List connections by domain\nconnections, err := scalekitClient.Connection().ListConnectionsByDomain(ctx, \n domain)" }, { "label": "Java SDK", "lang": "java", "source": "// List connections by organization id\nListConnectionsResponse response = scalekitClient.connections(\n ).listConnections(organizationId);\n\n// List connections by domain\nListConnectionsResponse response = scalekitClient.connections(\n ).listConnectionsByDomain(\"your-domain.com\");" } ] } }, "/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/invites/organizations/{organization_id}/users/{id}/resend": { "patch": { "description": "Resends an invitation email to a user who has a pending or expired invitation in the specified organization. If the invitation has expired, a new invitation will be automatically created and sent. If the invitation is still valid, a reminder email will be sent instead. Use this endpoint when a user hasn't responded to their initial invitation and you need to send them a reminder or when the original invitation has expired. The invitation email includes a secure magic link that allows the user to complete their account setup and join the organization. Each resend operation increments the resent counter.", "tags": [ "Users" ], "summary": "Resend user invitation email", "operationId": "UserService_ResendInvite", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization containing the pending invitation. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "System-generated user ID of the user who has a pending invitation. Must start with 'usr_' and be 19-25 characters long.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully resent the invitation email. Returns the updated invitation object with organization ID, user ID, membership status, timestamps, and resent count. If expired, a new invitation is created; otherwise, the existing one is resent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersResendInviteResponse" } } } }, "400": { "description": "Invalid request — common causes include user ID or organization ID is invalid, full-stack authentication is disabled, user profile is missing, invite already accepted, or missing expiry time in user management settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errdetailsErrorInfo" } } } }, "404": { "description": "Resource not found — the specified user, organization, membership, or invitation could not be found in the specified environment. Verify that all IDs are correct and that the resources exist before attempting to resend an invitation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errdetailsErrorInfo" } } } }, "500": { "description": "Internal server error — an unexpected error occurred while processing the invitation resend request. This may be due to database connectivity issues, problems generating the secure magic link, email delivery service failures, or transaction errors during invitation processing. Contact support if the problem persists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errdetailsErrorInfo" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserServiceResendInviteBody" } } }, "required": true } } }, "/api/v1/logs/authentication/requests": { "get": { "description": "Returns a paginated list of authentication request logs for the current environment, ordered most-recent first. Use this endpoint to audit login activity, investigate failed authentications. Filter by email, status (INITIATED, PENDING, SUCCESS, FAILED), time window, resource ID, or client ID. Status filters are case-insensitive. The response includes cursor tokens for forward and backward pagination and the total matching count. Pass next_page_token or prev_page_token as page_token on the next call to page through results.", "tags": [ "Authentication Logs" ], "summary": "List authentication requests", "operationId": "AuditLogsService_ListAuthRequests", "parameters": [ { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of authentication requests to return in a single page. If omitted, the server applies a default page size.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Opaque cursor from a previous response's next_page_token or prev_page_token. Omit on the first request.", "name": "page_token", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter authentication requests by the end-user email associated with the login attempt.", "name": "email", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "INITIATED", "PENDING", "SUCCESS", "FAILED" ] } }, "style": "form", "explode": true, "description": "Filter by authentication request status. Accepted values: INITIATED, PENDING, SUCCESS, FAILED. Matching is case-insensitive.", "name": "status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower bound for the authentication request timestamp (UTC). Only events at or after this time are returned.", "name": "start_time", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive upper bound for the authentication request timestamp (UTC). Only events at or before this time are returned.", "name": "end_time", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter authentication requests by resource identifier (for example an MCP resource ID).", "name": "resource_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter authentication logs by client ID", "name": "client_id", "in": "query" } ], "responses": { "200": { "description": "Authentication requests page returned successfully; includes authRequests, pagination tokens, and total_size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auditlogsListAuthLogResponse" } } } }, "400": { "description": "Invalid request - page_token is malformed, or status filter value is not one of INITIATED, PENDING, SUCCESS, or FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errdetailsErrorInfo" } } } }, "401": { "description": "Missing or invalid Authorization header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errdetailsErrorInfo" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Authentication Logs are not available in the Node.js SDK public API yet.\n// Use the REST API (GET /api/v1/logs/authentication/requests)." }, { "label": "Python SDK", "lang": "python", "source": "# Authentication Logs are not available in the Python SDK public API yet.\n# Use the REST API (GET /api/v1/logs/authentication/requests)." }, { "label": "Go SDK", "lang": "go", "source": "// Authentication Logs are not available in the Go SDK public API yet.\n// Use the REST API (GET /api/v1/logs/authentication/requests)." }, { "label": "Java SDK", "lang": "java", "source": "// Authentication Logs are not part of the Java SDK public API yet.\n// Use the REST API (GET /api/v1/logs/authentication/requests)." } ] } }, "/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. For a `META` server, the user needn't have connected accounts yet.", "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, `access_level` isn't `FULL` or `READ_ONLY`, the connection isn't an AgentKit connection, or the user has no active account on the connection. Depending on the environment, Scalekit instead creates a pending account for the user and 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/memberships/organizations/{organization_id}/users/{id}": { "post": { "description": "Adds an existing user to an organization and assigns them specific roles and permissions. Use this endpoint when you want to grant an existing user access to a particular organization. You can specify roles, metadata, and other membership details during the invitation process.", "tags": [ "Users" ], "summary": "Add existing user to organization", "operationId": "UserService_CreateMembership", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the target organization. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "System-generated user ID. Must start with 'usr_' (19-25 characters)", "name": "id", "in": "path", "required": true }, { "schema": { "type": "boolean" }, "description": "If true, sends an activation email to the user. Defaults to true.", "name": "send_invitation_email", "in": "query" } ], "responses": { "201": { "description": "User successfully added to the organization. Returns details of the updated membership details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersCreateMembershipResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Membership details to create. Required fields must be provided.", "required": [ "membership" ], "$ref": "#/components/schemas/v1usersCreateMembership" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.user.createMembership('org_123', 'usr_123', {\n roles: ['admin'],\n metadata: {\n department: 'engineering',\n location: 'nyc-office',\n },\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.users.users_pb2 import CreateMembership\nfrom scalekit.v1.commons.commons_pb2 import Role\n\nmembership = CreateMembership(\n roles=[Role(name=\"admin\")],\n metadata={\"department\": \"engineering\", \"location\": \"nyc-office\"},\n)\nresp = scalekit_client.users.create_membership(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n membership=membership,\n)" }, { "label": "Go SDK", "lang": "go", "source": "membership := &usersv1.CreateMembership{\n Roles: []*usersv1.Role{{Name: \"admin\"}},\n Metadata: map[string]string{\n \"department\": \"engineering\",\n \"location\": \"nyc-office\",\n },\n}\nresp, err := scalekitClient.User().CreateMembership(\n ctx,\n \"org_123\",\n \"usr_123\",\n membership,\n false,\n)\nif err != nil {\n // handle error\n return\n}\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "CreateMembershipRequest membershipReq = CreateMembershipRequest.newBuilder()\n .setMembership(\n CreateMembership.newBuilder()\n .addRoles(Role.newBuilder().setName(\"admin\").build())\n .putMetadata(\"department\", \"engineering\")\n .putMetadata(\"location\", \"nyc-office\")\n .build())\n .build();\nCreateMembershipResponse res = scalekitClient.users().createMembership(\n \"org_123\",\n \"usr_123\",\n membershipReq\n);" } ] }, "delete": { "description": "Removes a user from an organization by user ID. This action is irreversible and may also remove related group memberships.", "tags": [ "Users" ], "summary": "Delete organization membership for user", "operationId": "UserService_DeleteMembership", "parameters": [ { "schema": { "type": "string" }, "description": "Unique organization identifier. Must start with 'org_' and be 1-32 characters long", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "System-generated user ID. Must start with 'usr_' (19-25 characters)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "User successfully marked for deletion. No content returned", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.user.deleteMembership('org_123', 'usr_123')" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.users.delete_membership(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.User().DeleteMembership(\n ctx,\n \"org_123\",\n \"usr_123\",\n false, // cascade: also remove from nested groups when true\n)\nif err != nil {\n // handle error\n return\n}" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.users().deleteMembership(\"org_123\", \"usr_123\");" } ] }, "patch": { "description": "Updates a user's membership details within an organization by user ID. You can update roles and membership metadata.", "tags": [ "Users" ], "summary": "Update organization membership for user", "operationId": "UserService_UpdateMembership", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization containing the membership. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "System-generated user ID. Must start with 'usr_' and be 19-25 characters long.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Membership updated successfully. Returns the updated user object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersUpdateMembershipResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Membership fields to update. Only specified fields will be modified.", "$ref": "#/components/schemas/v1usersUpdateMembership", "examples": [ { "role": "admin" } ] } } }, "required": true } } }, "/api/v1/memberships/organizations/{organization_id}/users:external/{external_id}": { "post": { "description": "Adds an existing user to an organization using your application's external identifier for the user. Use this endpoint when you store users in Scalekit using your own system's identifiers and need to manage their organization memberships without storing Scalekit's internal user ID.", "tags": [ "Users" ], "summary": "Add existing user to organization by external ID", "operationId": "UserService_CreateMembership2", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the target organization. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "External system identifier from connected directories. Must be unique across the system", "name": "external_id", "in": "path", "required": true }, { "schema": { "type": "boolean" }, "description": "If true, sends an activation email to the user. Defaults to true.", "name": "send_invitation_email", "in": "query" } ], "responses": { "201": { "description": "User successfully added to the organization. Returns details of the updated membership details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersCreateMembershipResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Membership details to create. Required fields must be provided.", "required": [ "membership" ], "$ref": "#/components/schemas/v1usersCreateMembership" } } }, "required": true } }, "delete": { "description": "Removes a user from an organization using your application's external identifier for the user. Use this endpoint to revoke organization access without needing to store Scalekit's internal user ID.", "tags": [ "Users" ], "summary": "Delete organization membership by external ID", "operationId": "UserService_DeleteMembership2", "parameters": [ { "schema": { "type": "string" }, "description": "Unique organization identifier. Must start with 'org_' and be 1-32 characters long", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "External system identifier from connected directories. Must match existing records", "name": "external_id", "in": "path", "required": true } ], "responses": { "200": { "description": "User successfully marked for deletion. No content returned", "content": { "application/json": { "schema": {} } } } } }, "patch": { "description": "Updates a user's membership details within an organization using your application's external identifier for the user. Use this endpoint to update roles and membership metadata without needing to store Scalekit's internal user ID.", "tags": [ "Users" ], "summary": "Update organization membership by external ID", "operationId": "UserService_UpdateMembership2", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization containing the membership. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Your application's unique identifier for this user.", "name": "external_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Membership updated successfully. Returns the updated user object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersUpdateMembershipResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Membership fields to update. Only specified fields will be modified.", "$ref": "#/components/schemas/v1usersUpdateMembership", "examples": [ { "role": "admin" } ] } } }, "required": true } } }, "/api/v1/organizations": { "get": { "description": "Retrieve a paginated list of organizations within your environment. The response includes a `page_token` that can be used to access subsequent pages of results.", "tags": [ "Organizations" ], "summary": "List organizations", "operationId": "OrganizationService_ListOrganization", "parameters": [ { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of organizations to return per page. Must be between 10 and 100", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token from the previous response. Use to retrieve the next page of organizations", "name": "page_token", "in": "query" }, { "schema": { "type": "string" }, "description": "Your application's unique identifier for this organization, used to link Scalekit with your system", "name": "external_id", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the list of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsListOrganizationsResponse" } } } }, "400": { "description": "Invalid page token", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const organizations = await scalekit.organization.listOrganization({\n pageSize: 10,\n})" }, { "label": "Python SDK", "lang": "python", "source": "options = ListOrganizationOptions()\noptions.page_size = 10\n\norganizations = scalekit_client.organization.list_organizations(\n options=options\n)" }, { "label": "Go SDK", "lang": "go", "source": "organizations, err := scalekitClient.Organization().ListOrganization(\n ctx,\n &scalekit.ListOrganizationOptions{\n PageSize: 10,\n },\n)" }, { "label": "Java SDK", "lang": "java", "source": "ListOrganizationsResponse organizations = scalekitClient.organizations().listOrganizations(10, \"\");" } ] }, "post": { "description": "Creates a new organization in your environment. Use this endpoint to add a new tenant that can be configured with various settings and metadata", "tags": [ "Organizations" ], "summary": "Create an organization", "operationId": "OrganizationService_CreateOrganization", "responses": { "201": { "description": "Returns the newly created organization with its unique identifier and settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsCreateOrganizationResponse" } } } } }, "x-badges": [ { "name": "" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Required parameters for creating a new organization", "$ref": "#/components/schemas/v1organizationsCreateOrganization" } } }, "description": "Organization details", "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const organization = await scalekit.organization.createOrganization(name, {\n externalId: 'externalId',\n})" }, { "label": "Python SDK", "lang": "python", "source": "options = CreateOrganizationOptions()\noptions.external_id = \"externalId\"\norganization = scalekit_client.organization.create_organization(\n name,\n options=options\n)" }, { "label": "Go SDK", "lang": "go", "source": "organization, err := scalekitClient.Organization().CreateOrganization(\n ctx,\n name,\n scalekit.CreateOrganizationOptions{\n ExternalId: \"externalId\",\n },\n)" }, { "label": "Java SDK", "lang": "java", "source": "CreateOrganization createOrganization = CreateOrganization.newBuilder()\n .setDisplayName(\"Test Org\")\n .build();\n\nOrganization createdOrganization = scalekitClient.organizations().create(createOrganization);" } ] } }, "/api/v1/organizations/{id}": { "get": { "description": "Retrieves organization details by Scalekit ID, including name, region, metadata, and settings", "tags": [ "Organizations" ], "summary": "Get organization details", "operationId": "OrganizationService_GetOrganization", "parameters": [ { "schema": { "type": "string" }, "description": "Unique Scalekit-generated identifier for an organization. Use this with the GetOrganization endpoint. Do not pass this parameter when calling GetOrganizationByExternalId — use external_id instead.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the complete organization object with ID, display name, settings, and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsGetOrganizationResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const organization = await scalekit.organization.getOrganization(organizationId)" }, { "label": "Python SDK", "lang": "python", "source": "organization = scalekit_client.organization.get_organization(organization_id)" }, { "label": "Go SDK", "lang": "go", "source": "organization, err := scalekitClient.Organization().GetOrganization(\n ctx,\n organizationId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "ScalekitClient scalekitClient = new ScalekitClient(\n \"\",\n \"\",\n \"\"\n);\n\nOrganization organization = scalekitClient.organizations().getById(organizationId);" } ] }, "delete": { "description": "Remove an existing organization from the environment using its unique identifier", "tags": [ "Organizations" ], "summary": "Delete an organization", "operationId": "OrganizationService_DeleteOrganization", "parameters": [ { "schema": { "type": "string" }, "description": "Unique scalekit-generated identifier that uniquely references an organization", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Organization successfully deleted and no longer accessible", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.organization.deleteOrganization(organizationId)" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.organization.delete_organization(organization_id)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Organization().DeleteOrganization(\n ctx,\n organizationId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "ScalekitClient scalekitClient = new ScalekitClient(\n \"\",\n \"\",\n \"\"\n);\n\nscalekitClient.organizations().deleteById(organizationId);" } ] }, "patch": { "description": "Updates an organization's display name, external ID, or metadata. Requires a valid organization identifier. Region code cannot be modified through this endpoint.", "tags": [ "Organizations" ], "summary": "Update organization details", "operationId": "OrganizationService_UpdateOrganization", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization to be updated", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the updated organization with all current details reflected in the response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsUpdateOrganizationResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Organization Parameters to be updated", "$ref": "#/components/schemas/v1organizationsUpdateOrganization" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const organization = await scalekit.organization.updateOrganization(organization_id, {\n displayName: 'displayName',\n externalId: 'externalId',\n})" }, { "label": "Python SDK", "lang": "python", "source": "organization = scalekit_client.organization.update_organization(organization_id, {\n display_name: \"display_name\",\n external_id: \"external_id\"\n})" }, { "label": "Go SDK", "lang": "go", "source": "organization, err := scalekitClient.Organization().UpdateOrganization(\n ctx,\n organizationId,\n &scalekit.UpdateOrganization{\n DisplayName: \"displayName\",\n ExternalId: \"externalId\",\n },\n)" }, { "label": "Java SDK", "lang": "java", "source": "UpdateOrganization updateOrganization = UpdateOrganization.newBuilder()\n .setDisplayName(\"Updated Organization Name\")\n .build();\n\nOrganization updatedOrganizationById = scalekitClient.organizations().updateById(organizationId, updateOrganization);" } ] } }, "/api/v1/organizations/{id}/portal_links": { "put": { "description": "Creates a single use Admin Portal URL valid for 1 minute. Once the generated admin portal URL is accessed or rendered, a temporary session of 6 hours is created to allow the admin to update SSO/SCIM configuration.", "tags": [ "Organizations" ], "summary": "Generate admin portal link", "operationId": "OrganizationService_GeneratePortalLink", "parameters": [ { "schema": { "type": "string" }, "description": "Organization ID", "name": "id", "in": "path", "required": true }, { "schema": { "type": "array", "items": { "enum": [ "dir_sync", "sso" ], "type": "string" } }, "style": "form", "explode": true, "description": "Features to enable in the admin portal link. To enable features, append them as URL parameters:\n\n- Single Sign-On: ?features=sso\n- Directory Sync: ?features=dir_sync\n- Both features: ?features=sso&features=dir_sync\n\nExample URL: https://example.com/portal/lnk_{id}?features=sso\n\n - dir_sync: Enables directory synchronization configuration in the portal\n - sso: Enables Single Sign-On (SSO) configuration in the portal", "name": "features", "in": "query" } ], "responses": { "200": { "description": "Admin Portal link generated successfully. Returns the portal URL and expiration timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsGeneratePortalLinkResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const link = await scalekit.organization.generatePortalLink(organizationId)" }, { "label": "Python SDK", "lang": "python", "source": "link = scalekit_client.organization.generate_portal_link(\n organization_id\n)" }, { "label": "Go SDK", "lang": "go", "source": "link, err := scalekitClient.Organization().GeneratePortalLink(\n ctx,\n organizationId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "Link portalLink = client\n .organizations()\n .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync));" } ] } }, "/api/v1/organizations/{id}/settings": { "patch": { "description": "Updates configuration settings for an organization. Supports modifying SSO configuration, directory synchronization settings, and session parameters. Requires organization ID and the specific settings to update.", "tags": [ "Organizations" ], "summary": "Toggle organization settings", "operationId": "OrganizationService_UpdateOrganizationSettings", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization to update settings. Must begin with 'org_' prefix", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the complete organization object with updated settings applied. Contains all organization details including ID, display name, and the modified settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsGetOrganizationResponse" } } } }, "400": { "description": "Invalid request - occurs when the settings payload contains invalid values or unsupported configuration", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Organization not found - the specified organization ID doesn't exist", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Settings configuration to apply to the organization. Contains feature toggles for SSO, directory synchronization, and other organization capabilities", "$ref": "#/components/schemas/organizationsOrganizationSettings", "examples": [ { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] } ] } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const settings = {\n features: [\n {\n name: 'sso',\n enabled: true,\n },\n {\n name: 'dir_sync',\n enabled: true,\n },\n ],\n}\n\nawait scalekit.organization.updateOrganizationSettings('', settings)" }, { "label": "Python SDK", "lang": "python", "source": "settings = [\n {\n \"name\": \"sso\",\n \"enabled\": True\n },\n {\n \"name\": \"dir_sync\",\n \"enabled\": True\n }\n ]\n\nscalekit_client.organization.update_organization_settings(\n organization_id='', settings=settings\n)" }, { "label": "Go SDK", "lang": "go", "source": "settings := OrganizationSettings{\n\n\t\tFeatures: []Feature{\n\n\t\t\t{\n\n\t\t\t\tName: \"sso\",\n\n\t\t\t\tEnabled: true,\n\n\t\t\t},\n\n\t\t\t{\n\n\t\t\t\tName: \"dir_sync\",\n\n\t\t\t\tEnabled: true,\n\n\t\t\t},\n\n\t\t},\n\n\t}\n\n\norganization,err := scalekitClient.Organization().UpdateOrganizationSettings(ctx, organizationId, settings)" }, { "label": "Java SDK", "lang": "java", "source": "OrganizationSettingsFeature featureSSO = OrganizationSettingsFeature.newBuilder()\n .setName(\"sso\")\n .setEnabled(true)\n .build();\n\nOrganizationSettingsFeature featureDirectorySync = OrganizationSettingsFeature.newBuilder()\n .setName(\"dir_sync\")\n .setEnabled(true)\n .build();\n\nupdatedOrganization = scalekitClient.organizations()\n .updateOrganizationSettings(organization.getId(), List.of(featureSSO,\nfeatureDirectorySync));" } ] } }, "/api/v1/organizations/{org_id}/roles": { "get": { "description": "Retrieves all environment roles and organization specific roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization.", "tags": [ "Roles" ], "summary": "List organization roles", "operationId": "RolesService_ListOrganizationRoles", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "org_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions)", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved list of organization roles. Returns all roles with their metadata and optionally their permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesListOrganizationRolesResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.listOrganizationRoles('org_123')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.roles.list_organization_roles(org_id=\"org_123\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().ListOrganizationRoles(ctx, \"org_123\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "ListOrganizationRolesResponse res = scalekitClient.roles().listOrganizationRoles(\"org_123\");" } ] }, "post": { "description": "Creates a new role within the specified organization with basic configuration including name, display name, description, and permissions. Use this endpoint to define custom roles that can be assigned to users within the organization. You can create hierarchical roles by extending existing roles and assign specific permissions to control access levels. The role will be scoped to the organization and can be used for organization-specific access control.", "tags": [ "Roles" ], "summary": "Create organization role", "operationId": "RolesService_CreateOrganizationRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "org_id", "in": "path", "required": true } ], "responses": { "201": { "description": "Organization role created successfully. Returns the complete role object with system-generated ID and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesCreateOrganizationRoleResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Organization role details", "$ref": "#/components/schemas/v1rolesCreateOrganizationRole" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.role.createOrganizationRole('org_123', {\n name: 'org_admin',\n displayName: 'Org Admin',\n description: 'Organization-scoped role',\n extends: 'base_role_name', // optional\n permissions: ['perm.read', 'perm.write'], // optional\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole\n\nrole = CreateOrganizationRole(\n name=\"org_admin\",\n display_name=\"Org Admin\",\n description=\"Organization-scoped role\",\n extends=\"base_role_name\", # optional\n permissions=[\"perm.read\", \"perm.write\"] # optional\n)\n\nscalekit_client.roles.create_organization_role(\n org_id=\"org_123\",\n role=role\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().CreateOrganizationRole(ctx, \"org_123\", &rolesv1.CreateOrganizationRole{\n\n\tName: \"org_admin\",\n\n\tDisplayName: \"Org Admin\",\n\n\tDescription: proto.String(\"Organization-scoped role\"), // optional\n\n\tExtends: proto.String(\"base_role_name\"), // optional\n\n\tPermissions: []string{\"perm.read\", \"perm.write\"}, // optional\n\n})" }, { "label": "Java SDK", "lang": "java", "source": "CreateOrganizationRoleResponse res = scalekitClient.roles().createOrganizationRole(\n \"org_123\",\n CreateOrganizationRoleRequest.newBuilder()\n .setOrgId(\"org_123\")\n .setRole(\n CreateOrganizationRole.newBuilder()\n .setName(\"org_admin\")\n .setDisplayName(\"Org Admin\")\n .setDescription(\"Organization-scoped role\")\n .setExtends(\"base_role_name\") // optional\n .addPermissions(\"perm.read\") // optional\n .addPermissions(\"perm.write\") // optional\n .build()\n )\n .build()\n);" } ] } }, "/api/v1/organizations/{org_id}/roles/{role_name}": { "get": { "description": "Retrieves complete information for a specific organization role including metadata, inheritance details, and optionally permissions. Use this endpoint to audit role configuration and understand the role's place in the organization's role hierarchy. You can include permission details to see what capabilities the role provides. This operation is useful for role management, user assignment decisions, or understanding organization access controls.", "tags": [ "Roles" ], "summary": "Get organization role details", "operationId": "RolesService_GetOrganizationRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "org_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique name of the role", "name": "role_name", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions)", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved organization role details. Returns the role object including metadata and inheritance details. Permissions are included only when requested via the include parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesGetOrganizationRoleResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.getOrganizationRole('org_123', 'org_admin')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.roles.get_organization_role(\n org_id=\"org_123\",\n role_name=\"org_admin\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().GetOrganizationRole(ctx, \"org_123\", \"org_admin\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "GetOrganizationRoleResponse res = scalekitClient.roles().getOrganizationRole(\"org_123\", \"org_admin\");" } ] }, "put": { "description": "Modifies an existing organization role's properties including display name, description, permissions, and inheritance settings. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy within the organization. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.", "tags": [ "Roles" ], "summary": "Update organization role", "operationId": "RolesService_UpdateOrganizationRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "org_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique name of the role", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Organization role updated successfully. Returns the modified role object with updated timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateOrganizationRoleResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Organization role details", "$ref": "#/components/schemas/v1rolesUpdateRole" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.role.updateOrganizationRole('org_123', 'org_admin', {\n displayName: 'Org Admin (Updated)',\n description: 'Updated org role description',\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import UpdateRole\n\nscalekit_client.roles.update_organization_role(\n org_id=\"org_123\",\n role_name=\"org_admin\",\n role=UpdateRole(\n display_name=\"Org Admin (Updated)\",\n description=\"Updated org role description\"\n )\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().UpdateOrganizationRole(ctx, \"org_123\", \"org_admin\", &rolesv1.UpdateRole{\n DisplayName: \"Org Admin (Updated)\",\n Description: \"Updated org role description\",\n})\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "UpdateOrganizationRoleResponse res = scalekitClient.roles().updateOrganizationRole(\n \"org_123\",\n \"org_admin\",\n UpdateOrganizationRoleRequest.newBuilder()\n .setRole(\n UpdateRole.newBuilder()\n .setDisplayName(\"Org Admin (Updated)\")\n .setDescription(\"Updated org role description\")\n .build()\n )\n .build()\n);" } ] }, "delete": { "description": "Permanently removes a role from the organization and optionally reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your organization's access control system. If users are assigned to the role being deleted, you can provide a reassign_role_name to move those users to a different role before deletion. This action cannot be undone, so ensure no critical users depend on the role before deletion.", "tags": [ "Roles" ], "summary": "Delete organization role", "operationId": "RolesService_DeleteOrganizationRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "org_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique name of the role", "name": "role_name", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Role name to reassign users to when deleting this role", "name": "reassign_role_name", "in": "query" } ], "responses": { "200": { "description": "Organization role successfully deleted and users reassigned if specified. No content returned.", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Basic delete\nawait scalekit.role.deleteOrganizationRole('org_123', 'org_role_admin')\n\n// With reassignment\nawait scalekit.role.deleteOrganizationRole('org_123', 'org_role_admin', 'org_role_member')" }, { "label": "Python SDK", "lang": "python", "source": "# Basic delete\nscalekit_client.roles.delete_organization_role(\n org_id=\"org_123\",\n role_name=\"org_role_admin\"\n)\n\n# With reassignment\nscalekit_client.roles.delete_organization_role(\n org_id=\"org_123\",\n role_name=\"org_role_admin\",\n reassign_role_name=\"org_role_member\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "// Basic delete\nerr := scalekitClient.Role().DeleteOrganizationRole(ctx, \"org_123\", \"org_role_admin\")\nif err != nil { /* handle err */ }\n\n// With reassignment\nerr = scalekitClient.Role().DeleteOrganizationRole(ctx, \"org_123\", \"org_role_admin\", \"org_role_member\")" }, { "label": "Java SDK", "lang": "java", "source": "// Basic delete\nscalekitClient.roles().deleteOrganizationRole(\"org_123\", \"org_role_admin\");\n\n// With reassignment\nscalekitClient.roles().deleteOrganizationRole(\"org_123\", \"org_role_admin\", \"org_role_member\");" } ] } }, "/api/v1/organizations/{org_id}/roles:set_defaults": { "patch": { "description": "Updates the default member role for the specified organization. Use this endpoint to configure which role is automatically assigned to new users when they join the organization. The system will validate that the specified role exists and update the organization settings accordingly. This configuration affects all new user invitations and memberships within the organization.", "tags": [ "Roles" ], "summary": "Set default organization roles", "operationId": "RolesService_UpdateDefaultOrganizationRoles", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "org_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Default organization roles updated successfully. Returns the updated default member role object with complete role information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateDefaultOrganizationRolesResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.updateDefaultOrganizationRoles('org_123', {\n defaultMemberRole: 'org_member',\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import UpdateDefaultOrganizationRolesRequest\n\nres = scalekit_client.roles.update_default_organization_roles(\n org_id=\"org_123\",\n default_roles=UpdateDefaultOrganizationRolesRequest(\n default_member_role=\"org_member\"\n )\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().UpdateDefaultOrganizationRoles(ctx, \"org_123\", \"org_member\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "UpdateDefaultOrganizationRolesResponse res = scalekitClient.roles().updateDefaultOrganizationRoles(\n \"org_123\",\n UpdateDefaultOrganizationRolesRequest.newBuilder()\n .setDefaultMemberRole(\"org_member\")\n .build()\n);" } ] } }, "/api/v1/organizations/{organization_id}/clients": { "get": { "description": "Retrieves a paginated list of API clients for a specific organization. Returns client details including metadata, scopes, and secret information (without exposing actual secret values).", "tags": [ "API Auth" ], "summary": "List organization API clients", "operationId": "ClientService_ListOrganizationClients", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization whose clients to list. Must start with 'org_' prefix.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of clients to return per page\n\nMaximum number of API clients to return per page. Must be between 10 and 100", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token from the previous response\n\nPagination token from the previous response. Use to retrieve the next page of organization clients", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "List of organization API clients returned successfully. Each client includes its configuration details and metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/clientsListOrganizationClientsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.m2m.listOrganizationClients('org_123', {\n pageSize: 30,\n})\nconst clients = response.clients" }, { "label": "Python SDK", "lang": "python", "source": "# List clients for a specific organization\norg_id = \"org_123\"\n\nresponse = scalekit_client.m2m_client.list_organization_clients(\n organization_id=org_id,\n page_size=30,\n)\n\nclients = response.clients\nfor client in clients:\n print(f\"Client ID: {client.id}, Name: {client.name}\")" }, { "label": "Go SDK", "lang": "go", "source": "response, err := scalekitClient.M2M().ListOrganizationClients(\n ctx,\n \"org_123\",\n scalekit.ListOrganizationClientsOptions{\n PageSize: 30,\n },\n)\nif err != nil {\n // handle error\n return\n}\n_ = response" }, { "label": "Java SDK", "lang": "java", "source": "ListOrganizationClientsResponse response = scalekitClient.m2m()\n .listOrganizationClients(\"org_123\", 30, \"\");" } ] }, "post": { "description": "Creates a new API client for an organization. Returns the client details and a plain secret (available only once).", "tags": [ "API Auth" ], "summary": "Create organization API client", "operationId": "ClientService_CreateOrganizationClient", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true } ], "responses": { "201": { "description": "API client created successfully. Returns the client ID and plain secret (only available at creation time). The client can be configured with scopes, audience values, and custom claims for fine-grained access control.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/clientsCreateOrganizationClientResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Details of the client to be created", "$ref": "#/components/schemas/clientsOrganizationClient" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.m2m.createOrganizationClient('org_123', {\n name: 'GitHub Actions Deployment Service',\n description: 'Service account for GitHub Actions to deploy applications to production',\n scopes: ['deploy:applications', 'read:deployments'],\n audience: ['deployment-api.acmecorp.com'],\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.clients.clients_pb2 import OrganizationClient\n\nm2m_client = OrganizationClient(\n name=\"GitHub Actions Deployment Service\",\n description=\"Service account for GitHub Actions to deploy applications to production\",\n custom_claims=[\n {\"key\": \"github_repository\", \"value\": \"acmecorp/inventory-service\"},\n {\"key\": \"environment\", \"value\": \"production_us\"},\n ],\n scopes=[\"deploy:applications\", \"read:deployments\"],\n audience=[\"deployment-api.acmecorp.com\"],\n expiry=3600,\n)\n\nresponse = scalekit_client.m2m_client.create_organization_client(\n organization_id=\"org_123\",\n m2m_client=m2m_client,\n)" }, { "label": "Go SDK", "lang": "go", "source": "response, err := scalekitClient.M2M().CreateOrganizationClient(\n ctx,\n \"org_123\",\n scalekit.CreateOrganizationClientOptions{\n Name: \"GitHub Actions Deployment Service\",\n Description: \"Service account for GitHub Actions to deploy applications to production\",\n Scopes: []string{\"deploy:applications\", \"read:deployments\"},\n Audience: []string{\"deployment-api.acmecorp.com\"},\n },\n)\nif err != nil {\n // handle error\n return\n}\n_ = response" }, { "label": "Java SDK", "lang": "java", "source": "import com.scalekit.grpc.scalekit.v1.clients.OrganizationClient;\n\nOrganizationClient orgClient = OrganizationClient.newBuilder()\n .setName(\"GitHub Actions Deployment Service\")\n .setDescription(\"Service account for GitHub Actions to deploy applications to production\")\n .addScopes(\"deploy:applications\")\n .addScopes(\"read:deployments\")\n .addAudience(\"deployment-api.acmecorp.com\")\n .build();\n\nCreateOrganizationClientResponse response = scalekitClient.m2m()\n .createOrganizationClient(\"org_123\", orgClient);" } ] } }, "/api/v1/organizations/{organization_id}/clients/{client_id}": { "get": { "description": "Retrieves details of a specific API client in an organization.", "tags": [ "API Auth" ], "summary": "Get organization API client", "operationId": "ClientService_GetOrganizationClient", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the API client", "name": "client_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the complete API client configuration, including all current settings and a list of active secrets. Note that secret values are not included in the response for security reasons.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/clientsGetOrganizationClientResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.m2m.getOrganizationClient('org_123', 'skc_xxxxx')" }, { "label": "Python SDK", "lang": "python", "source": "import os\n\norg_id = \"org_123\"\nclient_id = os.environ[\"M2M_CLIENT_ID\"]\n\nresponse = scalekit_client.m2m_client.get_organization_client(\n organization_id=org_id,\n client_id=client_id,\n)" }, { "label": "Go SDK", "lang": "go", "source": "response, err := scalekitClient.M2M().GetOrganizationClient(\n ctx,\n \"org_123\",\n \"skc_xxxxx\",\n)\nif err != nil {\n // handle error\n return\n}\n_ = response" }, { "label": "Java SDK", "lang": "java", "source": "GetOrganizationClientResponse response = scalekitClient.m2m()\n .getOrganizationClient(\"org_123\", \"skc_xxxxx\");" } ] }, "delete": { "description": "Permanently deletes an API client from an organization. This operation cannot be undone and will revoke all access for the client. All associated secrets will also be invalidated. Use this endpoint to remove unused or compromised clients.", "tags": [ "API Auth" ], "summary": "Delete organization API client", "operationId": "ClientService_DeleteOrganizationClient", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization that owns the client. Must start with 'org_' prefix.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the API client to permanently delete. Must start with 'm2morg_' prefix.", "name": "client_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Organization API client successfully deleted and no longer accessible", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.m2m.deleteOrganizationClient('org_123', 'skc_xxxxx')" }, { "label": "Python SDK", "lang": "python", "source": "import os\n\norg_id = \"org_123\"\nclient_id = os.environ[\"M2M_CLIENT_ID\"]\n\nscalekit_client.m2m_client.delete_organization_client(\n organization_id=org_id,\n client_id=client_id,\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.M2M().DeleteOrganizationClient(\n ctx,\n \"org_123\",\n \"skc_xxxxx\",\n)\nif err != nil {\n // handle error\n return\n}" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.m2m().deleteOrganizationClient(\"org_123\", \"skc_xxxxx\");" } ] }, "patch": { "description": "Updates an existing organization API client. Only specified fields are modified.", "tags": [ "API Auth" ], "summary": "Update organization API client", "operationId": "ClientService_UpdateOrganizationClient", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the client", "name": "client_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the updated organization API client with all current details reflected in the response, including modified scopes, audience values, and custom claims.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/clientsUpdateOrganizationClientResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Updated details for the client", "$ref": "#/components/schemas/clientsOrganizationClient" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.m2m.updateOrganizationClient('org_123', 'skc_xxxxx', {\n description: 'Service account for GitHub Actions to deploy applications to production_eu',\n})" }, { "label": "Python SDK", "lang": "python", "source": "import os\nfrom scalekit.v1.clients.clients_pb2 import OrganizationClient\n\norg_id = \"org_123\"\nclient_id = os.environ[\"M2M_CLIENT_ID\"]\n\nupdate_m2m_client = OrganizationClient(\n description=\"Service account for GitHub Actions to deploy applications to production_eu\",\n custom_claims=[\n {\"key\": \"github_repository\", \"value\": \"acmecorp/inventory\"},\n {\"key\": \"environment\", \"value\": \"production_eu\"},\n ],\n)\n\nresponse = scalekit_client.m2m_client.update_organization_client(\n organization_id=org_id,\n client_id=client_id,\n m2m_client=update_m2m_client,\n)" }, { "label": "Go SDK", "lang": "go", "source": "response, err := scalekitClient.M2M().UpdateOrganizationClient(\n ctx,\n \"org_123\",\n \"skc_xxxxx\",\n scalekit.UpdateOrganizationClientOptions{\n Description: \"Service account for GitHub Actions to deploy applications to production_eu\",\n },\n)\nif err != nil {\n // handle error\n return\n}\n_ = response" }, { "label": "Java SDK", "lang": "java", "source": "import com.scalekit.grpc.scalekit.v1.clients.OrganizationClient;\n\nOrganizationClient updates = OrganizationClient.newBuilder()\n .setDescription(\"Service account for GitHub Actions to deploy applications to production_eu\")\n .build();\n\nUpdateOrganizationClientResponse response = scalekitClient.m2m()\n .updateOrganizationClient(\"org_123\", \"skc_xxxxx\", updates);" } ] } }, "/api/v1/organizations/{organization_id}/clients/{client_id}/secrets": { "post": { "description": "Creates a new secret for an organization API client. Returns the plain secret (available only once).", "tags": [ "API Auth" ], "summary": "Create organization API client secret", "operationId": "ClientService_CreateOrganizationClientSecret", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the API client", "name": "client_id", "in": "path", "required": true } ], "responses": { "201": { "description": "Client secret created successfully. Returns the new secret ID and the plain secret value (only available at creation time). The secret can be used immediately for authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/clientsCreateOrganizationClientSecretResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.m2m.addOrganizationClientSecret('org_123', 'skc_xxxxx')\nconst secretId = response.secret?.id" }, { "label": "Python SDK", "lang": "python", "source": "import os\n\norg_id = \"org_123\"\nclient_id = os.environ[\"M2M_CLIENT_ID\"]\n\nresponse = scalekit_client.m2m_client.add_organization_client_secret(\n organization_id=org_id,\n client_id=client_id,\n)\n\n# with_call returns (response, call)\nsecret_id = response[0].secret.id" }, { "label": "Go SDK", "lang": "go", "source": "response, err := scalekitClient.M2M().CreateOrganizationClientSecret(\n ctx,\n \"org_123\",\n \"skc_xxxxx\",\n)\nif err != nil {\n // handle error\n return\n}\n_ = response" }, { "label": "Java SDK", "lang": "java", "source": "CreateOrganizationClientSecretResponse response = scalekitClient.m2m()\n .createOrganizationClientSecret(\"org_123\", \"skc_xxxxx\");" } ] } }, "/api/v1/organizations/{organization_id}/clients/{client_id}/secrets/{secret_id}": { "delete": { "description": "Permanently deletes a secret from an organization API client. This operation cannot be undone.", "tags": [ "API Auth" ], "summary": "Delete organization API client secret", "operationId": "ClientService_DeleteOrganizationClientSecret", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the API client", "name": "client_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the client secret", "name": "secret_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Client secret successfully deleted and no longer accessible", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.m2m.removeOrganizationClientSecret('org_123', 'skc_xxxxx', 'sks_xxxxx')" }, { "label": "Python SDK", "lang": "python", "source": "import os\n\norg_id = \"org_123\"\nclient_id = os.environ[\"M2M_CLIENT_ID\"]\nsecret_id = os.environ[\"M2M_SECRET_ID\"]\n\nscalekit_client.m2m_client.remove_organization_client_secret(\n organization_id=org_id,\n client_id=client_id,\n secret_id=secret_id,\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.M2M().DeleteOrganizationClientSecret(\n ctx,\n \"org_123\",\n \"skc_xxxxx\",\n \"sks_xxxxx\",\n)\nif err != nil {\n // handle error\n return\n}" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.m2m().deleteOrganizationClientSecret(\n \"org_123\",\n \"skc_xxxxx\",\n \"sks_xxxxx\"\n);" } ] } }, "/api/v1/organizations/{organization_id}/connections/{id}": { "get": { "description": "Retrieves the complete configuration and status details for a specific connection by its ID within an organization. Returns all connection properties including provider settings, protocols, and current status.", "tags": [ "Connections" ], "summary": "Get connection details", "operationId": "ConnectionService_GetConnection", "parameters": [ { "schema": { "type": "string" }, "description": "Organization identifier (required). Specifies which organization owns the connection you want to retrieve.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Connection identifier (required). Specifies which specific connection to retrieve from the organization.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved connection details for the specified organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsGetConnectionResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const connection = await scalekit.connection.getConnection(organizationId, connectionId)" }, { "label": "Python SDK", "lang": "python", "source": "connection = scalekit_client.connection.get_connection(\n organization_id,\n connection_id,\n)" }, { "label": "Go SDK", "lang": "go", "source": "connection, err := scalekitClient.Connection().GetConnection(\n ctx,\n organizationId,\n connectionId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "Connection connection = scalekitClient.connections().getConnectionById(connectionId, organizationId);" } ] }, "delete": { "description": "Deletes an SSO connection from the specified organization by connection ID. Use this endpoint when an identity provider integration is no longer needed for the organization. Returns an empty response after the SSO connection is deleted successfully.", "tags": [ "Connections" ], "summary": "Delete SSO connection", "operationId": "ConnectionService_DeleteConnection", "parameters": [ { "schema": { "type": "string" }, "description": "Organization ID for the Connection.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Connection ID. Unique ID for the connection", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "SSO connection deleted successfully", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.connection.deleteConnection(organizationId, connectionId)" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.connection.delete_connection(\n organization_id,\n connection_id\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Connection().DeleteConnection(\n ctx,\n organizationId,\n connectionId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.connections().deleteConnection(connectionId, organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/connections/{id}:disable": { "patch": { "description": "Deactivate an existing connection for the specified organization. When disabled, users cannot authenticate using this connection. This endpoint changes the connection state from enabled to disabled without modifying other configuration settings", "tags": [ "Connections" ], "summary": "Disable SSO connection", "operationId": "ConnectionService_DisableConnection", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization associated with the connection", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier for the connection to be toggled", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Connection disabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsToggleConnectionResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.connection.disableConnection(organizationId, connectionId)" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.connection.disable_connection(\n organization_id,\n connection_id\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Connection().DisableConnection(\n ctx,\n organizationId,\n connectionId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "ToggleConnectionResponse response = scalekitClient.connections().disableConnection(connectionId, organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/connections/{id}:enable": { "patch": { "description": "Activate an existing connection for the specified organization. When enabled, users can authenticate using this connection. This endpoint changes the connection state from disabled to enabled without modifying other configuration settings", "tags": [ "Connections" ], "summary": "Enable SSO connection", "operationId": "ConnectionService_EnableConnection", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization associated with the connection", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier for the connection to be toggled", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Connection enabled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connectionsToggleConnectionResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.connection.enableConnection(organizationId, connectionId)" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.connection.enable_connection(\n organization_id,\n connection_id,\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Connection().EnableConnection(\n ctx,\n organizationId,\n connectionId,\n)" }, { "label": "Java SDK", "lang": "java", "source": "ToggleConnectionResponse response = scalekitClient.connections().enableConnection(connectionId, organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/directories": { "get": { "tags": [ "Directory" ], "summary": "List organization directories", "operationId": "DirectoryService_ListDirectories", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved the list of directories for the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directoriesListDirectoriesResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.directory.listDirectories('')" }, { "label": "Python SDK", "lang": "python", "source": "directories_list = scalekit_client.directory.list_directories(\n\torganization_id=''\n)" }, { "label": "Go SDK", "lang": "go", "source": "directories,err := scalekitClient.Directory().ListDirectories(ctx, organizationId)" }, { "label": "Java SDK", "lang": "java", "source": "ListDirectoriesResponse response = scalekitClient.directories().listDirectories(organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/directories/{directory_id}/groups": { "get": { "description": "Retrieves all groups from a specified directory. Use this endpoint to view group structures from your connected identity provider.", "tags": [ "Directory" ], "summary": "List directory groups", "operationId": "DirectoryService_ListDirectoryGroups", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the directory", "name": "directory_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Number of groups to return per page. Maximum value is 30. If not specified, defaults to 10", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Token for pagination. Use the value returned in the 'next_page_token' field of the previous response", "name": "page_token", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Filter groups updated after this timestamp. Use ISO 8601 format", "name": "updated_after", "in": "query" }, { "schema": { "type": "boolean" }, "description": "If true, includes full group details. If false or not specified, returns basic information only", "name": "include_detail", "in": "query" }, { "schema": { "type": "boolean" }, "description": "If true, returns group and its details from external provider (default: false)", "name": "include_external_groups", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the list of groups from the specified directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directoriesListDirectoryGroupsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { groups } = await scalekit.directory.listDirectoryGroups(\n '',\n '',\n)" }, { "label": "Python SDK", "lang": "python", "source": "directory_groups = scalekit_client.directory.list_directory_groups(\n directory_id='', organization_id=''\n)" }, { "label": "Go SDK", "lang": "go", "source": "options := &ListDirectoryGroupsOptions{\n\n\t\tPageSize: 10,\n\n\t\tPageToken:\"\",\n\n\t}\n\n\ndirectoryGroups, err := scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options)" }, { "label": "Java SDK", "lang": "java", "source": "var options = ListDirectoryResourceOptions.builder()\n .pageSize(10)\n .pageToken(\"\")\n .includeDetail(true)\n .build();\n\nListDirectoryGroupsResponse groupsResponse = scalekitClient\n .directories()\n .listDirectoryGroups(directory.getId(), organizationId, options);" } ] } }, "/api/v1/organizations/{organization_id}/directories/{directory_id}/users": { "get": { "description": "Retrieves a list of all users within a specified directory for an organization. This endpoint allows you to view user accounts associated with your connected Directory Providers.", "tags": [ "Directory" ], "summary": "List directory users", "operationId": "DirectoryService_ListDirectoryUsers", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the directory within the organization", "name": "directory_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Number of users to return per page. Maximum value is 30. If not specified, defaults to 10", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Token for pagination. Use the value returned in the 'next_page_token' field of the previous response to retrieve the next page of results", "name": "page_token", "in": "query" }, { "schema": { "type": "boolean" }, "description": "If set to true, the response will include the full user payload with all available details. If false or not specified, only essential user information will be returned", "name": "include_detail", "in": "query" }, { "schema": { "type": "string" }, "description": "Filter users by their membership in a specific directory group", "name": "directory_group_id", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Filter users that were updated after the specified timestamp. Use ISO 8601 format", "name": "updated_after", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the list of users from the specified directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directoriesListDirectoryUsersResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { users } = await scalekit.directory.listDirectoryUsers('', '')" }, { "label": "Python SDK", "lang": "python", "source": "directory_users = scalekit_client.directory.list_directory_users(\n directory_id='', organization_id=''\n)" }, { "label": "Go SDK", "lang": "go", "source": "options := &ListDirectoryUsersOptions{\n\n\t\tPageSize: 10,\n\n\t\tPageToken: \"\",\n\n\t}\n\ndirectoryUsers,err := scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options)" }, { "label": "Java SDK", "lang": "java", "source": "var options = ListDirectoryResourceOptions.builder()\n .pageSize(10)\n .pageToken(\"\")\n .includeDetail(true)\n .build();\n\nListDirectoryUsersResponse usersResponse = scalekitClient\n .directories()\n .listDirectoryUsers(directory.getId(), organizationId, options);" } ] } }, "/api/v1/organizations/{organization_id}/directories/{id}": { "get": { "description": "Retrieves detailed information about a specific directory within an organization", "tags": [ "Directory" ], "summary": "Get directory details", "operationId": "DirectoryService_GetDirectory", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier of the directory", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved directory details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directoriesGetDirectoryResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { directory } = await scalekit.directory.getDirectory(organizationId, directoryId)" }, { "label": "Python SDK", "lang": "python", "source": "directory = scalekit_client.directory.get_directory(\n directory_id='', organization_id=''\n)\nprint(f'Directory details: {directory}')" }, { "label": "Go SDK", "lang": "go", "source": "directory, err := scalekitClient.Directory().GetDirectory(ctx, organizationId, directoryId)" }, { "label": "Java SDK", "lang": "java", "source": "Directory directory = scalekitClient.directories().getDirectory(directoryId, organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/directories/{id}:disable": { "patch": { "description": "Stops synchronization of users and groups from a specified directory within an organization. This operation prevents further updates from the connected Directory provider", "tags": [ "Directory" ], "summary": "Disable a directory", "operationId": "DirectoryService_DisableDirectory", "parameters": [ { "schema": { "type": "string" }, "description": "A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully disabled the directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directoriesToggleDirectoryResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.directory.disableDirectory('', '')" }, { "label": "Python SDK", "lang": "python", "source": "directory_response = scalekit_client.directory.disable_directory(\n directory_id='', organization_id=''\n)" }, { "label": "Go SDK", "lang": "go", "source": "disable,err := scalekitClient.Directory().DisableDirectory(ctx, organizationId, directoryId)" }, { "label": "Java SDK", "lang": "java", "source": "ToggleDirectoryResponse disableResponse = scalekitClient\n .directories()\n .disableDirectory(directoryId, organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/directories/{id}:enable": { "patch": { "description": "Activates a directory within an organization, allowing it to synchronize users and groups with the connected Directory provider", "tags": [ "Directory" ], "summary": "Enable a directory", "operationId": "DirectoryService_EnableDirectory", "parameters": [ { "schema": { "type": "string" }, "description": "A unique identifier for the organization. The value must begin with 'org_' and be between 1 and 32 characters long", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "A unique identifier for a directory within the organization. The value must begin with 'dir_' and be between 1 and 32 characters long", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directoriesToggleDirectoryResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.directory.enableDirectory('', '')" }, { "label": "Python SDK", "lang": "python", "source": "directory_response = scalekit_client.directory.enable_directory(\n directory_id='', organization_id=''\n)" }, { "label": "Go SDK", "lang": "go", "source": "enable,err := scalekitClient.Directory().EnableDirectory(ctx, organizationId, directoryId)" }, { "label": "Java SDK", "lang": "java", "source": "ToggleDirectoryResponse enableResponse = client\n .directories()\n .enableDirectory(directoryId, organizationId);" } ] } }, "/api/v1/organizations/{organization_id}/domains": { "get": { "description": "Retrieves a paginated list of all domains configured for the specified organization.\n\nDomain types:\n- ALLOWED_EMAIL_DOMAIN: Trusted domains used to suggest the organization in the organization switcher during sign-in/sign-up (auth-method agnostic).\n- ORGANIZATION_DOMAIN: SSO discovery domains used to route users to the correct SSO provider and enforce SSO.\n\n", "tags": [ "Domains" ], "summary": "List Domains", "operationId": "DomainService_ListDomains", "parameters": [ { "schema": { "type": "string" }, "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Optional comma-separated list of additional fields to include in the response (e.g., 'verification_details').", "name": "include", "in": "query" }, { "schema": { "type": "integer", "format": "int32" }, "description": "Maximum number of domains to return per page. Default is 30, maximum is 100.", "name": "page_size", "in": "query" }, { "schema": { "type": "integer", "format": "int32" }, "description": "Page number to retrieve (0-based). Use 0 for the first page.", "name": "page_number", "in": "query" }, { "schema": { "type": "string", "enum": [ "ALLOWED_EMAIL_DOMAIN", "ORGANIZATION_DOMAIN" ] }, "description": "The domain type.\n- ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up.\n- ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO.\n", "name": "domain_type", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the list of domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domainsListDomainResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// List all domains in an organization\nconst response = await scalekit.domain.listDomains(organizationId, {\n domainType: 'ORGANIZATION_DOMAIN',\n})\n\n// Domain object contains:\n// - id: Domain identifier\n// - domain: Domain name\n// - organizationId: Owning organization\n// - domainType: Configuration type" }, { "label": "Python SDK", "lang": "python", "source": "# List all domains in an organization\nresponse = scalekit_client.domain.list_domains(\n organization_id=\"org_123\",\n domain_type=\"ORGANIZATION_DOMAIN\"\n )\n# - organization_id: Owning organization\n# - domain_type: domain type" }, { "label": "Go SDK", "lang": "go", "source": "domains, err := scalekitClient.Domain().ListDomains(ctx, \"org_id\", &scalekit.ListDomainOptions{\nDomainType: \"ORGANIZATION_DOMAIN\",\n})" }, { "label": "Java SDK", "lang": "java", "source": "List domains = scalekitClient.domains().listDomainsByOrganizationId(\"org_id\", \"ORGANIZATION_DOMAIN\");" } ] }, "post": { "description": "Creates and associates a domain with an organization.\n\nUse one of the following domain types:\n- ALLOWED_EMAIL_DOMAIN: Adds a trusted email domain for organization suggestions in the organization switcher during sign-in/sign-up (auth-method agnostic).\n- ORGANIZATION_DOMAIN: Enables SSO domain discovery. If a user signs in with a matching email domain, Scalekit redirects them to the organization’s SSO provider and enforces SSO.\n\nThe domain must be a valid business domain that you control. Public/disposable domains (e.g., gmail.com) are blocked for security.\n\n", "tags": [ "Domains" ], "summary": "Create Domain", "operationId": "DomainService_CreateDomain", "parameters": [ { "schema": { "type": "string" }, "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully created the domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domainsCreateDomainResponse" } } } }, "400": { "description": "Invalid request — common causes invalid domain format, public or disposable domain, or domain already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errdetailsErrorInfo" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Domain configuration including the domain name and type.", "$ref": "#/components/schemas/v1domainsCreateDomain" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Add a new domain to an organization\nconst response = await scalekit.createDomain('org-123', 'example.com', {\n // Domain type: controls user authentication and email validation\n\n domainType: 'ORGANIZATION_DOMAIN',\n})" }, { "label": "Python SDK", "lang": "python", "source": "# Add a new domain to an organization\nresponse = scalekit_client.domain.create_domain(organization_id=\"org-123\",\n\n\t\t\tdomain_name=\"example.com\",\n \t\t\tdomain_type=\"ORGANIZATION_DOMAIN\")" }, { "label": "Go SDK", "lang": "go", "source": "domain, err := scalekitClient.Domain().CreateDomain(ctx, \"org_id\", \"example.com\", &scalekit.CreateDomainOptions{\n\n\t\tDomainType: \"ORGANIZATION_DOMAIN\",\n\n\t})" }, { "label": "Java SDK", "lang": "java", "source": "CreateDomainRequest request = CreateDomainRequest.newBuilder()\n\t.setOrganizationId(organization.getId())\n\t.setDomain(CreateDomain.newBuilder()\n\t\t.setDomain(\"example.com\")\n\t\t.setDomainType(\"ORGANIZATION_DOMAIN\")\n\t\t.build())\n\t.build();\n\t\nDomain domain = scalekitClient.domains().createDomain(request);" } ] } }, "/api/v1/organizations/{organization_id}/domains/{id}": { "get": { "description": "Retrieves complete details for a domain including domain type, timestamps, and configuration information.\n\n", "tags": [ "Domains" ], "summary": "Get Domain", "operationId": "DomainService_GetDomain", "parameters": [ { "schema": { "type": "string" }, "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Scalekit-generated unique identifier of the domain to retrieve.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved the domain details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/domainsGetDomainResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Fetch details of a specific domain\nconst response = await scalekit.domain.getDomain(organizationId, domainId)\n\n// Domain object properties:\n// - id: Domain identifier\n// - domain: Domain name\n// - organizationId: Owning organization\n// - domainType: Domain configuration type" }, { "label": "Python SDK", "lang": "python", "source": "# Fetch details of a specific domain\nresponse = scalekit_client.domain.get_domain(organization_id=\"org_123\", domain_id=\"dom_123\")" }, { "label": "Go SDK", "lang": "go", "source": "domain, err := scalekitClient.Domain().GetDomain(ctx, \"dom_123\", \"org_123\")" }, { "label": "Java SDK", "lang": "java", "source": "Domain domain = scalekitClient.domains().getDomainById(\"org_123\", \"dom_123\");" } ] }, "delete": { "description": "Permanently removes a domain record from an organization.\n\n- Deleting an ORGANIZATION_DOMAIN disables SSO routing/enforcement for that domain.\n- Deleting an ALLOWED_EMAIL_DOMAIN stops organization suggestions for users with that email domain.\n\n", "tags": [ "Domains" ], "summary": "Delete Domain", "operationId": "DomainService_DeleteDomain", "parameters": [ { "schema": { "type": "string" }, "description": "Scalekit-generated unique identifier for the organization. Use either this or external_id to identify the organization.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Scalekit-generated unique identifier of the domain to be permanently deleted.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Domain successfully deleted.", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Remove a domain from an organization\n// Caution: Deletion is permanent and may affect user access\nconst response = await scalekit.domain.deleteDomain(organizationId, domainId)" }, { "label": "Python SDK", "lang": "python", "source": "# Remove a domain from an organization\n# Caution: Deletion is permanent and may affect user access\nresponse = scalekit_client.domain.delete_domain(\n organization_id=\"org_123\",\n domain_id=\"dom_123\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "err = scalekitClient.Domain().DeleteDomain(ctx, \"dom_123\", \"org_123\")" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.domains().deleteDomain(organization.getId(), domain.getId());" } ] } }, "/api/v1/organizations/{organization_id}/session-policy": { "get": { "description": "Retrieves the session policy for an organization. Returns session_policy='APPLICATION' if the organization inherits the application-level defaults, or session_policy='CUSTOM' with the configured values if a custom policy is active.", "tags": [ "Organizations" ], "summary": "Get organization session policy", "operationId": "OrganizationService_GetOrganizationSessionPolicy", "parameters": [ { "schema": { "type": "string" }, "description": "The unique identifier of the organization whose session policy is being requested.", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Session policy retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsGetOrganizationSessionPolicyResponse" } } } }, "404": { "description": "Organization not found.", "content": { "application/json": { "schema": {} } } } } }, "patch": { "description": "Sets a custom session policy for an organization or reverts to application-level settings. Send session_policy='APPLICATION' to revert to application defaults. Send session_policy='CUSTOM' with timeout values to activate a custom policy.", "tags": [ "Organizations" ], "summary": "Update organization session policy", "operationId": "OrganizationService_UpdateOrganizationSessionPolicy", "parameters": [ { "schema": { "type": "string" }, "description": "The unique identifier of the organization whose session policy is being updated.", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Session policy updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsUpdateOrganizationSessionPolicyResponse" } } } }, "404": { "description": "Organization not found.", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationServiceUpdateOrganizationSessionPolicyBody" } } }, "required": true } } }, "/api/v1/organizations/{organization_id}/settings/usermanagement": { "patch": { "description": "Upsert user management settings for an organization", "tags": [ "Organizations" ], "summary": "Upsert organization user setting", "operationId": "OrganizationService_UpsertUserManagementSettings", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the organization.", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Returns the updated organization setting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsUpsertUserManagementSettingsResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationServiceUpsertUserManagementSettingsBody" } } }, "required": true } } }, "/api/v1/organizations/{organization_id}/users": { "get": { "description": "Retrieves a paginated list of all users who are members of the specified organization. Use this endpoint to view all users with access to a particular organization, including their roles, metadata, and membership details. Supports pagination for large user lists.", "tags": [ "Users" ], "summary": "List organization users", "operationId": "UserService_ListOrganizationUsers", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization for which to list users. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of users to return in a single response. Valid range: 1-100. Server may return fewer users than specified.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token from a previous ListUserResponse. Used to retrieve the next page of results. Leave empty for the first request.", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the list of users in the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersListOrganizationUsersResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.user.listOrganizationUsers('org_123', {\n pageSize: 50,\n})\nconsole.log(response.users)" }, { "label": "Python SDK", "lang": "python", "source": "response = scalekit_client.users.list_organization_users(\n organization_id=\"org_123\",\n page_size=50,\n)" }, { "label": "Go SDK", "lang": "go", "source": "list, \n err := scalekitClient.User().ListOrganizationUsers(ctx, \"org_123\", &scalekit.ListUsersOptions{PageSize:\n50}) if err != nil { /* handle error */ }\nfmt.Println(list.Users)" }, { "label": "Java SDK", "lang": "java", "source": "ListOrganizationUsersRequest listReq = ListOrganiz\n ationUsersRequest.newBuilder()\n .setPageSize(50)\n .build();\nListOrganizationUsersResponse list = users.\n listOrganizationUsers(\"org_123\", listReq);" } ] }, "post": { "description": "Creates a new user account and immediately adds them to the specified organization. Use this endpoint when you want to create a user and grant them access to an organization in a single operation. You can provide user profile information, assign roles, and configure membership metadata. The user receives an activation email unless this feature is disabled in the organization settings.", "tags": [ "Users" ], "summary": "Create new user in organization", "operationId": "UserService_CreateUserAndMembership", "parameters": [ { "schema": { "type": "string" }, "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "boolean" }, "description": "If true, sends an activation email to the user. Defaults to true.", "name": "send_invitation_email", "in": "query" } ], "responses": { "201": { "description": "User created successfully. Returns the created user object, including system-generated identifiers and timestamps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersCreateUserAndMembershipResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersCreateUser" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { user } = await scalekit.user.createUserAndMembership('org_123', {\n email: 'user@example.com',\n externalId: 'ext_12345a67b89c',\n metadata: { department: 'engineering', location: 'nyc-office' },\n userProfile: {\n firstName: 'John',\n lastName: 'Doe',\n },\n})" }, { "label": "Python SDK", "lang": "python", "source": "# Create user with membership \nuser = CreateUser(\n email=\"john.doe@example.com\",\n external_id=\"ext_john_123\", # Optional\n user_profile={\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"name\": \"John Doe\",\n \"locale\": \"en-US\",\n \"phone_number\": \"+14155552671\"\n },\n membership={\n \"roles\": [{\"name\": \"member\"}] \n }\n)\n\n# Create user and membership in organization\nresponse = scalekit_client.users.create_user_and_membership(\n organization_id=\"your_org_id\",\n user=user,\n send_invitation_email=True # Set to False if you don't want to send\nemail )\n\n user_id = response[0].user.id" }, { "label": "Go SDK", "lang": "go", "source": "newUser := &usersv1.CreateUser{\n Email: \"user@example.com\",\n ExternalId: \"ext_12345a67b89c\",\n Metadata: map[string]string{\n \"department\": \"engineering\",\n \"location\": \"nyc-office\",\n },\n UserProfile: &usersv1.CreateUserProfile{\n FirstName: \"John\",\n LastName: \"Doe\",\n },\n}\ncuResp, \n err := scalekitClient.User().CreateUserAndMembership(ctx, \"org_123\",\nnewUser, false) if err != nil { /* handle error */ }" }, { "label": "Java SDK", "lang": "java", "source": "CreateUser createUser = CreateUser.newBuilder()\n .setEmail(\"user@example.com\")\n .setExternalId(\"ext_12345a67b89c\")\n .putMetadata(\"department\", \"engineering\")\n .putMetadata(\"location\", \"nyc-office\")\n .setUserProfile(\n CreateUserProfile.newBuilder()\n .setFirstName(\"John\")\n .setLastName(\"Doe\")\n .build())\n .build();\nCreateUserAndMembershipRequest cuReq = CreateUserA\n ndMembershipRequest.newBuilder()\n .setUser(createUser)\n .build();\nCreateUserAndMembershipResponse cuResp = users.\n createUserAndMembership(\"org_123\", cuReq);\nSystem.out.println(cuResp.getUser().getId());" } ] } }, "/api/v1/organizations/{organization_id}/users/{user_id}/permissions": { "get": { "description": "Retrieves all permissions a user has access to within a specific organization. This includes permissions from direct role assignments and inherited permissions from role hierarchy.", "tags": [ "Users" ], "summary": "List user permissions", "operationId": "UserService_ListUserPermissions", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier for the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier for the user", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved the list of permissions for the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersListUserPermissionsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { permissions } = await scalekit.user.listUserPermissions('org_123', 'usr_123')" }, { "label": "Python SDK", "lang": "python", "source": "resp = scalekit_client.users.list_user_permissions(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n)\npermissions = resp.permissions" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.User().ListUserPermissions(ctx, \"org_123\", \"usr_123\")\nif err != nil {\n // handle error\n}\npermissions := resp.Permissions" }, { "label": "Java SDK", "lang": "java", "source": "ListUserPermissionsResponse resp = scalekitClient.users().listUserPermissions(\"org_123\", \"usr_123\");\nList permissions = resp.getPermissionsList();" } ] } }, "/api/v1/organizations/{organization_id}/users/{user_id}/roles": { "get": { "description": "Retrieves all roles assigned to a user within a specific organization. This includes both direct role assignments and inherited roles from role hierarchy.", "tags": [ "Users" ], "summary": "List user roles", "operationId": "UserService_ListUserRoles", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier for the organization", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique identifier for the user", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved the list of roles assigned to the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersListUserRolesResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { roles } = await scalekit.user.listUserRoles('org_123', 'usr_123')" }, { "label": "Python SDK", "lang": "python", "source": "resp = scalekit_client.users.list_user_roles(\n organization_id=\"org_123\",\n user_id=\"usr_123\",\n)\nroles = resp.roles" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.User().ListUserRoles(ctx, \"org_123\", \"usr_123\")\nif err != nil {\n // handle error\n}\nroles := resp.Roles" }, { "label": "Java SDK", "lang": "java", "source": "ListUserRolesResponse resp = scalekitClient.users().listUserRoles(\"org_123\", \"usr_123\");\nList roles = resp.getRolesList();" } ] } }, "/api/v1/organizations/{organization_id}/users:search": { "get": { "description": "Searches for users within a specific organization by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Scopes results strictly to the given organization. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages.", "tags": [ "Users" ], "summary": "Search organization users", "operationId": "UserService_SearchOrganizationUsers", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier of the organization to search within. Must start with 'org_' and be 1-32 characters long.", "name": "organization_id", "in": "path", "required": true }, { "schema": { "type": "string", "minLength": 3, "maxLength": 100 }, "description": "Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive.", "name": "query", "in": "query", "required": true }, { "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 30 }, "description": "Maximum number of users 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" } ], "responses": { "200": { "description": "Matching users within the organization returned; includes pagination cursors for navigating large result sets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersSearchOrganizationUsersResponse" } } } }, "400": { "description": "Bad Request - query must be at least 3 characters and no more than 100 characters, and organization_id must be a valid org_ prefixed identifier.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not Found - organization not found.", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/organizations:external/{external_id}": { "get": { "description": "Retrieves organization details by external ID, including name, region, metadata, and settings. Only provide external_id in the path. If the id query parameter is also supplied, it silently takes precedence over external_id due to protobuf oneof semantics, which causes the request to fail with a 400 Bad Request ('ExternalId is required').", "tags": [ "Organizations" ], "summary": "Get organization details by external Id", "operationId": "OrganizationService_GetOrganizationByExternalId", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier that links an organization to your app's tenant. Use this with the GetOrganizationByExternalId endpoint. Only one of id or external_id should be provided per request.", "name": "external_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique Scalekit-generated identifier for an organization. Use this with the GetOrganization endpoint. Do not pass this parameter when calling GetOrganizationByExternalId — use external_id instead.", "name": "id", "in": "query" } ], "responses": { "200": { "description": "Returns the complete organization object with ID, display name, settings, external ID and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organizationsGetOrganizationResponse" } } } }, "400": { "description": "Invalid request - external ID is empty or the caller's organization claim does not match", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Organization not found - no organization exists with the specified external ID", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/passwordless/email/resend": { "post": { "description": "Resend a verification email if the user didn't receive it or if the previous code/link has expired", "tags": [ "Magic link & OTP" ], "summary": "Resend passwordless email", "operationId": "PasswordlessService_ResendPasswordlessEmail", "responses": { "200": { "description": "Successfully resent the passwordless authentication email. Returns updated authentication request details with new expiration time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessSendPasswordlessResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessResendPasswordlessRequest" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { authRequestId } = sendResponse\nconst resendResponse = await scalekit.passwordless.resendPasswordlessEmail(authRequestId)" }, { "label": "Python SDK", "lang": "python", "source": "resend_response = scalekit_client.passwordless.resend_passwordless_email(\n auth_request_id=auth_request_id,\n)\n\n# New auth request ID from resend\nnew_auth_request_id = resend_response[0].auth_request_id" }, { "label": "Go SDK", "lang": "go", "source": "resendResponse, err := scalekitClient.Passwordless().ResendPasswordlessEmail(\n ctx,\n authRequestId,\n)\n\nif err != nil {\n // Handle error\n return\n}" }, { "label": "Java SDK", "lang": "java", "source": "SendPasswordlessResponse resendResponse = scalekitClient.passwordless()\n .resendPasswordlessEmail(authRequestId);" } ] } }, "/api/v1/passwordless/email/send": { "post": { "description": "Send a verification email containing either a verification code (OTP), magic link, or both to a user's email address", "tags": [ "Magic link & OTP" ], "summary": "Send passwordless email", "operationId": "PasswordlessService_SendPasswordlessEmail", "responses": { "200": { "description": "Successfully sent passwordless authentication email. Returns the authentication request details including expiration time and auth request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessSendPasswordlessResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessSendPasswordlessRequest" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.passwordless.sendPasswordlessEmail('john.doe@example.com', {\n template: 'SIGNIN',\n expiresIn: 100,\n magiclinkAuthUri: 'https://yourapp.com/auth/passwordless/callback',\n templateVariables: {\n employeeID: 'EMP523',\n teamName: 'Alpha Team',\n supportEmail: 'support@yourcompany.com',\n },\n})" }, { "label": "Python SDK", "lang": "python", "source": "response = scalekit_client.passwordless.send_passwordless_email(\n email=\"john.doe@example.com\",\n template=\"SIGNIN\", # or \"SIGNUP\", \"UNSPECIFIED\"\n expires_in=100,\n magiclink_auth_uri=\"https://yourapp.com/auth/passwordless/callback\",\n template_variables={\n \"employeeID\": \"EMP523\",\n \"teamName\": \"Alpha Team\",\n \"supportEmail\": \"support@yourcompany.com\",\n },\n)\n\n# with_call returns (response, call)\nauth_request_id = response[0].auth_request_id" }, { "label": "Go SDK", "lang": "go", "source": "templateType := scalekit.TemplateTypeSignin\nresponse, err := scalekitClient.Passwordless().SendPasswordlessEmail(\n ctx,\n \"john.doe@example.com\",\n &scalekit.SendPasswordlessOptions{\n Template: &templateType,\n ExpiresIn: 100,\n MagiclinkAuthUri: \"https://yourapp.com/auth/passwordless/callback\",\n TemplateVariables: map[string]string{\n \"employeeID\": \"EMP523\",\n \"teamName\": \"Alpha Team\",\n \"supportEmail\": \"support@yourcompany.com\",\n },\n },\n)\nif err != nil {\n // handle error\n return\n}\nauthRequestId := response.AuthRequestId" }, { "label": "Java SDK", "lang": "java", "source": "TemplateType templateType = TemplateType.SIGNIN;\nMap templateVariables = new HashMap<>();\ntemplateVariables.put(\"employeeID\", \"EMP523\");\ntemplateVariables.put(\"teamName\", \"Alpha Team\");\ntemplateVariables.put(\"supportEmail\", \"support@yourcompany.com\");\n\nSendPasswordlessOptions options = new SendPasswordlessOptions();\noptions.setTemplate(templateType);\noptions.setExpiresIn(100);\noptions.setMagiclinkAuthUri(\"https://yourapp.com/auth/passwordless/callback\");\noptions.setTemplateVariables(templateVariables);\n\nSendPasswordlessResponse response = scalekitClient.passwordless().sendPasswordlessEmail(\n \"john.doe@example.com\",\n options\n);\n\nString authRequestId = response.getAuthRequestId();" } ] } }, "/api/v1/passwordless/email/verify": { "post": { "description": "Verify a user's identity using either a verification code or magic link token", "tags": [ "Magic link & OTP" ], "summary": "Verify passwordless email", "operationId": "PasswordlessService_VerifyPasswordlessEmail", "responses": { "200": { "description": "Successfully verified the passwordless authentication. Returns user email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessVerifyPasswordLessResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessVerifyPasswordLessRequest" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { authRequestId } = sendResponse\n\n// Verify with OTP code\nconst verifyResponse = await scalekit.passwordless.verifyPasswordlessEmail(\n { code: '123456' },\n authRequestId,\n)\n\n// Or verify with magic link token\nconst linkVerifyResponse = await scalekit.passwordless.verifyPasswordlessEmail({\n linkToken: linkToken,\n})" }, { "label": "Python SDK", "lang": "python", "source": "# Verify with OTP code\nverify_response = scalekit_client.passwordless.verify_passwordless_email(\n code=\"123456\", # OTP code received via email\n auth_request_id=auth_request_id,\n)\n\n# Verify with magic link token\nverify_response = scalekit_client.passwordless.verify_passwordless_email(\n link_token=link_token, # Magic link token from URL\n)\n\n# User verified successfully\nuser_email = verify_response[0].email" }, { "label": "Go SDK", "lang": "go", "source": "// Verify with OTP code\nverifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail(\n ctx,\n &scalekit.VerifyPasswordlessOptions{\n Code: \"123456\", // OTP code\n AuthRequestId: authRequestId,\n },\n)\n\nif err != nil {\n // Handle error\n return\n}\n\n// Verify with magic link token\nverifyResponse, err := scalekitClient.Passwordless().VerifyPasswordlessEmail(\n ctx,\n &scalekit.VerifyPasswordlessOptions{\n LinkToken: linkToken, // Magic link token\n },\n)\n\nif err != nil {\n // Handle error\n return\n}\n\n// User verified successfully\nuserEmail := verifyResponse.Email" }, { "label": "Java SDK", "lang": "java", "source": "// Verify with OTP code\nVerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions();\nverifyOptions.setCode(\"123456\"); // OTP code\nverifyOptions.setAuthRequestId(authRequestId);\n\nVerifyPasswordLessResponse verifyResponse = scalekitClient.passwordless()\n .verifyPasswordlessEmail(verifyOptions);\n\n// User verified successfully\nString userEmail = verifyResponse.getEmail();\n\n// Verify with magic link token\nVerifyPasswordlessOptions linkVerifyOptions = new VerifyPasswordlessOptions();\nlinkVerifyOptions.setLinkToken(linkToken); // Magic link token\n\nVerifyPasswordLessResponse linkVerifyResponse = scalekitClient.passwordless()\n .verifyPasswordlessEmail(linkVerifyOptions);\n\nString verifiedEmail = linkVerifyResponse.getEmail();" } ] } }, "/api/v1/permissions": { "get": { "description": "Retrieves a comprehensive, paginated list of all permissions available within the environment. Use this endpoint to view all permission definitions for auditing, role management, or understanding the complete set of available access controls. The response includes pagination tokens to navigate through large sets of permissions efficiently. Each permission object contains the permission name, description, creation time, and last update time. This operation is useful for building permission selection interfaces, auditing permission usage, or understanding the scope of available access controls in your RBAC system.", "tags": [ "Permissions" ], "summary": "List all permissions", "operationId": "RolesService_ListPermissions", "parameters": [ { "schema": { "type": "string" }, "description": "Page token to retrieve next page of results", "name": "page_token", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "Number of permissions to return per page (max 100)", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "enum": [ "SCALEKIT", "ENVIRONMENT" ] }, "description": "Filter permissions by type: ALL, SCALEKIT, or ENVIRONMENT, where SCALEKIT are predefined Scalekit permissions and ENVIRONMENT are custom permissions created in the environment, default is ALL", "name": "type", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the list of permissions. Returns a paginated list of permission objects with metadata and pagination tokens for navigation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesListPermissionsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.permission.listPermissions()" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.permissions.list_permissions()" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().ListPermissions(ctx)\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "ListPermissionsResponse res = scalekitClient.permissions().listPermissions();" } ] }, "post": { "description": "Creates a new permission that represents a specific action users can perform within the environment. Use this endpoint to define granular access controls for your RBAC system. You can provide a unique permission name following the format 'action:resource' (for example, 'read:documents', 'write:users') and an optional description explaining the permission's purpose. The permission name must be unique across the environment and follows alphanumeric naming conventions with colons and underscores. Returns the created permission object including system-generated ID and timestamps.", "tags": [ "Permissions" ], "summary": "Create new permission", "operationId": "RolesService_CreatePermission", "responses": { "201": { "description": "Permission created successfully. Returns the complete permission object with system-generated ID, name, description, and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesCreatePermissionResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1rolesCreatePermission" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.permission.createPermission({\n name: 'read:users',\n description: 'Allows reading users',\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import CreatePermission\n\npermission = CreatePermission(\n name=\"read:users\",\n description=\"Allows reading users\"\n)\n\nscalekit_client.permissions.create_permission(permission=permission)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().CreatePermission(ctx, &rolesv1.CreatePermission{\n\n\tName: \"read:users\",\n\n\tDescription: \"Allows reading users\",\n\n})\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "CreatePermissionResponse res = scalekitClient.permissions().createPermission(\n CreatePermissionRequest.newBuilder()\n .setPermission(\n CreatePermission.newBuilder()\n .setName(\"read:users\")\n .setDescription(\"Allows reading users\")\n .build()\n )\n .build()\n);" } ] } }, "/api/v1/permissions/{permission_name}": { "get": { "description": "Retrieves complete information for a specific permission by its unique name identifier. Use this endpoint to view permission details including description, creation time, and last update time. Provide the permission name in the path parameter following the format 'action:resource' (for example, 'read:documents'). This operation is useful for auditing permission definitions, understanding permission purposes, or verifying permission existence before assignment. Returns the complete permission object with all metadata and system-generated timestamps.", "tags": [ "Permissions" ], "summary": "Retrieve permission details", "operationId": "RolesService_GetPermission", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the permission", "name": "permission_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved permission details. Returns the complete permission object including name, description, creation time, and update time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesGetPermissionResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.permission.getPermission('read:users')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.permissions.get_permission(\n permission_name=\"read:users\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().GetPermission(ctx, \"read:users\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "GetPermissionResponse res = scalekitClient.permissions().getPermission(\"read:users\");" } ] }, "put": { "description": "Modifies an existing permission's attributes including description and metadata. Use this endpoint to update permission descriptions or clarify permission purposes after creation. The permission is identified by its unique name in the path parameter, and only the fields you specify in the request body will be updated. Note that the permission name itself cannot be changed as it serves as the immutable identifier. This operation is useful for maintaining clear documentation of permission purposes or updating descriptions to reflect changes in system functionality. Returns the updated permission object with modified timestamps.", "tags": [ "Permissions" ], "summary": "Update permission details", "operationId": "RolesService_UpdatePermission", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the permission", "name": "permission_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Permission updated successfully. Returns the modified permission object with updated description and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdatePermissionResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1rolesCreatePermission" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.permission.updatePermission('read:users', {\n name: 'read:users',\n description: 'Allows reading user resources',\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import CreatePermission\n\nscalekit_client.permissions.update_permission(\n permission_name=\"read:users\",\n permission=CreatePermission(\n name=\"read:users\",\n description=\"Allows reading user resources\"\n )\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().UpdatePermission(ctx, \"read:users\", &rolesv1.CreatePermission{\n Name: \"read:users\",\n Description: \"Allows reading user resources\",\n})\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "UpdatePermissionResponse res = scalekitClient.permissions().updatePermission(\n \"read:users\",\n UpdatePermissionRequest.newBuilder()\n .setPermission(\n CreatePermission.newBuilder()\n .setName(\"read:users\")\n .setDescription(\"Allows reading user resources\")\n .build()\n )\n .build()\n);" } ] }, "delete": { "description": "Permanently removes a permission from the environment using its unique name identifier. Use this endpoint when you need to clean up unused permissions or remove access controls that are no longer relevant. The permission is identified by its name in the path parameter following the format 'action:resource'. This operation cannot be undone, so ensure no active roles depend on the permission before deletion. If the permission is currently assigned to any roles, you may need to remove those assignments first or update the roles to use alternative permissions. Returns no content on successful deletion.", "tags": [ "Permissions" ], "summary": "Delete permission", "operationId": "RolesService_DeletePermission", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the permission", "name": "permission_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Permission successfully deleted. No content returned.", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.permission.deletePermission('read:users')" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.permissions.delete_permission(\n permission_name=\"read:users\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Permission().DeletePermission(ctx, \"read:users\")\nif err != nil { /* handle err */ }" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.permissions().deletePermission(\"read:users\");" } ] } }, "/api/v1/roles": { "get": { "description": "Retrieves a comprehensive list of all roles available within the specified environment including organization roles. Use this endpoint to view all role definitions, including custom roles and their configurations. You can optionally include permission details for each role to understand their capabilities. This is useful for role management, auditing organization access controls, or understanding the available access levels within the organization.", "tags": [ "Roles" ], "summary": "List all roles in environment", "operationId": "RolesService_ListRoles", "parameters": [ { "schema": { "type": "string" }, "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions from role hierarchy)", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved list of roles. Returns all roles with their metadata and optionally their permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesListRolesResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.listRoles()" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.roles.list_roles()" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().ListRoles(ctx)\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "ListRolesResponse res = scalekitClient.roles().listRoles();" } ] }, "post": { "description": "Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform.", "tags": [ "Roles" ], "summary": "Create new role in environment", "operationId": "RolesService_CreateRole", "responses": { "201": { "description": "Role created successfully. Returns the complete role object with system-generated ID and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesCreateRoleResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Role configuration details including name, display name, description, permissions, and inheritance settings.", "$ref": "#/components/schemas/v1rolesCreateRole", "examples": [ { "description": "Can edit content", "display_name": "Content Editor", "name": "content_editor", "permissions": [ "read:content", "write:content" ] } ] } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.role.createRole({\n name: 'admin',\n displayName: 'Admin',\n description: 'Environment-level role',\n extends: 'base_role', // optional\n permissions: ['read:users'], // optional\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import CreateRole\n\nrole = CreateRole(\n name=\"admin\",\n display_name=\"Admin\",\n description=\"Environment-level role\",\n extends=\"base_role\", # optional\n permissions=[\"read:users\"] # optional\n)\n\nscalekit_client.roles.create_role(role=role)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().CreateRole(ctx, &rolesv1.CreateRole{\n\n\tName: \"admin\",\n\n\tDisplayName: \"Admin\",\n\n\tDescription: \"Environment-level role\",\n\n\tExtends: proto.String(\"base_role\"), // optional\n\n\tPermissions: []string{\"read:users\"}, // optional\n\n})" }, { "label": "Java SDK", "lang": "java", "source": "CreateRoleResponse res = scalekitClient.roles().createRole(\n CreateRoleRequest.newBuilder()\n .setRole(\n CreateRole.newBuilder()\n .setName(\"admin\")\n .setDisplayName(\"Admin\")\n .setDescription(\"Environment-level role\")\n // .setExtends(\"base_role\") // optional\n // .addPermissions(\"read:users\") // optional\n .build()\n )\n .build()\n);" } ] } }, "/api/v1/roles/default": { "patch": { "description": "Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions.", "tags": [ "Roles" ], "summary": "Set default creator and member roles", "operationId": "RolesService_UpdateDefaultRoles2", "responses": { "200": { "description": "Default roles updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateDefaultRolesResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateDefaultRolesRequest" } } }, "required": true } } }, "/api/v1/roles/{role_name}": { "get": { "description": "Retrieves complete information for a specific role including metadata and inheritance details (base role and dependent role count). Use this endpoint to audit role configuration and understand the role's place in the hierarchy. To view the role's permissions, use the ListRolePermissions endpoint.", "tags": [ "Roles" ], "summary": "Get role details", "operationId": "RolesService_GetRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique name identifier of the role to retrieve. Must be alphanumeric with underscores, 1-64 characters.", "name": "role_name", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Include additional data in the response. Valid values: 'permissions' (direct permissions only), 'permissions:all' (includes inherited permissions from role hierarchy)", "name": "include", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved role details. Returns the role object including metadata and inheritance details. Permissions are not included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesGetRoleResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.getRole('admin')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.roles.get_role(role_name=\"admin\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().GetRole(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "GetRoleResponse res = scalekitClient.roles().getRole(\"admin\");" } ] }, "put": { "description": "Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.", "tags": [ "Roles" ], "summary": "Update role information", "operationId": "RolesService_UpdateRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique name identifier of the role to update. Must be alphanumeric with underscores, 1-64 characters.", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Role updated successfully. Returns the modified role object with updated timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateRoleResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "Role fields to update. Only specified fields will be modified.", "$ref": "#/components/schemas/v1rolesUpdateRole", "examples": [ { "description": "Can edit and approve content", "display_name": "Senior Editor" } ] } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.role.updateRole('admin', {\n displayName: 'Admin (Updated)',\n description: 'Updated description',\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import UpdateRole\n\nscalekit_client.roles.update_role(\n role_name=\"admin\",\n role=UpdateRole(\n display_name=\"Admin (Updated)\",\n description=\"Updated description\"\n )\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().UpdateRole(ctx, \"admin\", &rolesv1.UpdateRole{\n DisplayName: \"Admin (Updated)\",\n Description: \"Updated description\",\n})\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "UpdateRoleResponse res = scalekitClient.roles().updateRole(\n \"admin\",\n UpdateRoleRequest.newBuilder()\n .setRole(\n UpdateRole.newBuilder()\n .setDisplayName(\"Admin (Updated)\")\n .setDescription(\"Updated description\")\n .build()\n )\n .build()\n);" } ] }, "delete": { "description": "Permanently removes a role from the environment and reassigns users who had that role to a different role. Use this endpoint when you need to clean up unused roles or restructure your access control system. The role cannot be deleted if it has dependent roles (roles that extend it) unless you specify a replacement role. If users are assigned to the role being deleted, you must provide a reassign_role_name to move those users to a different role before deletion can proceed. This action cannot be undone, so ensure no critical users depend on the role before deletion.", "tags": [ "Roles" ], "summary": "Delete role and reassign users", "operationId": "RolesService_DeleteRole", "parameters": [ { "schema": { "type": "string" }, "description": "Unique name identifier of the role to delete. Must be alphanumeric with underscores, 1-64 characters.", "name": "role_name", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Role name to reassign users to when deleting this role", "name": "reassign_role_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Role name to reassign users to when deleting this role", "name": "reassign_role_name", "in": "query" } ], "responses": { "200": { "description": "Role successfully deleted and users reassigned. No content returned.", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Basic delete\nawait scalekit.role.deleteRole('admin')\n\n// With reassignment\nawait scalekit.role.deleteRole('admin', 'member')" }, { "label": "Python SDK", "lang": "python", "source": "# Basic delete\nscalekit_client.roles.delete_role(role_name=\"admin\")\n\n# With reassignment\nscalekit_client.roles.delete_role(\n role_name=\"admin\",\n reassign_role_name=\"member\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "// Basic delete\nerr := scalekitClient.Role().DeleteRole(ctx, \"admin\")\nif err != nil { /* handle err */ }\n\n// With reassignment\nerr = scalekitClient.Role().DeleteRole(ctx, \"admin\", \"member\")" }, { "label": "Java SDK", "lang": "java", "source": "// Basic delete\nscalekitClient.roles().deleteRole(\"admin\");\n\n// With reassignment\nscalekitClient.roles().deleteRole(\"admin\", \"member\");" } ] } }, "/api/v1/roles/{role_name}/dependents": { "get": { "description": "Retrieves all roles that directly extend the specified base role through inheritance. Use this endpoint to understand the role hierarchy and identify which roles inherit permissions from a particular base role. Provide the base role name as a path parameter, and the response will include all dependent roles with their metadata and permission information. This operation is useful for auditing role inheritance relationships, understanding the impact of changes to base roles, or managing role hierarchies effectively. Returns a list of dependent role objects including their names, display names, descriptions, and permission details.", "tags": [ "Roles" ], "summary": "List dependent roles", "operationId": "RolesService_ListDependentRoles", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the base role", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved dependent roles. Returns a list of all roles that extend the specified base role, including their metadata and permission information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesListDependentRolesResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.listDependentRoles('admin')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.roles.list_dependent_roles(role_name=\"admin\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().ListDependentRoles(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "ListDependentRolesResponse res = scalekitClient.roles().listDependentRoles(\"admin\");" } ] } }, "/api/v1/roles/{role_name}/permissions": { "get": { "description": "Retrieves all permissions directly assigned to the specified role, excluding permissions inherited from base roles. Use this endpoint to view the explicit permission assignments for a role, which is useful for understanding direct role capabilities, auditing permission assignments, or managing role-permission relationships. Provide the role name as a path parameter, and the response will include only the permissions that are directly assigned to that role. This operation does not include inherited permissions from role hierarchies - use ListEffectiveRolePermissions to see the complete set of permissions including inheritance. Returns a list of permission objects with their names, descriptions, and assignment metadata.", "tags": [ "Roles" ], "summary": "List permissions for role", "operationId": "RolesService_ListRolePermissions", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the role", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved role permissions. Returns a list of all permissions directly assigned to the specified role, excluding inherited permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesListRolePermissionsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.permission.listRolePermissions('admin')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.permissions.list_role_permissions(role_name=\"admin\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().ListRolePermissions(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "ListRolePermissionsResponse res = scalekitClient.permissions().listRolePermissions(\"admin\");" } ] }, "post": { "description": "Adds one or more permissions to the specified role while preserving existing permission assignments. Use this endpoint to grant additional capabilities to a role without affecting its current permission set. Provide the role name as a path parameter and a list of permission names in the request body. The system will validate that all specified permissions exist in the environment and add them to the role. Existing permission assignments remain unchanged, making this operation safe for incremental permission management. This is useful for gradually expanding role capabilities or adding new permissions as your system evolves. Returns the updated list of all permissions now assigned to the role.", "tags": [ "Roles" ], "summary": "Add permissions to role", "operationId": "RolesService_AddPermissionsToRole", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the role", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Permissions added to role successfully. Returns the complete list of all permissions now assigned to the role, including both existing and newly added permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesAddPermissionsToRoleResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesServiceAddPermissionsToRoleBody" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.permission.addPermissionsToRole('role_admin', ['perm.read', 'perm.write'])" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.permissions.add_permissions_to_role(\n role_name=\"role_admin\",\n permission_names=[\"perm.read\", \"perm.write\"]\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().AddPermissionsToRole(ctx, \"role_admin\", []string{\"perm.read\", \"perm.write\"})" }, { "label": "Java SDK", "lang": "java", "source": "AddPermissionsToRoleResponse res = scalekitClient.permissions().addPermissionsToRole(\n \"role_admin\",\n AddPermissionsToRoleRequest.newBuilder()\n .addPermissionNames(\"perm.read\")\n .addPermissionNames(\"perm.write\")\n .build()\n);" } ] } }, "/api/v1/roles/{role_name}/permissions/{permission_name}": { "delete": { "description": "Removes a specific permission from the specified role, revoking that capability from all users assigned to the role. Use this endpoint to restrict role capabilities or remove unnecessary permissions. Provide both the role name and permission name as path parameters. This operation only affects the direct permission assignment and does not impact permissions inherited from base roles. If the permission is inherited through role hierarchy, you may need to modify the base role instead. This is useful for fine-tuning role permissions, implementing least-privilege access controls, or removing deprecated permissions. Returns no content on successful removal.", "tags": [ "Roles" ], "summary": "Remove permission from role", "operationId": "RolesService_RemovePermissionFromRole", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the role", "name": "role_name", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Name of the permission to remove", "name": "permission_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Permission removed from role successfully. No content returned.", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.permission.removePermissionFromRole('admin', 'read:users')" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.permissions.remove_permission_from_role(\n role_name=\"admin\",\n permission_name=\"read:users\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Permission().RemovePermissionFromRole(ctx, \"admin\", \"read:users\")\nif err != nil { /* handle err */ }" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.permissions().removePermissionFromRole(\"admin\", \"read:users\");" } ] } }, "/api/v1/roles/{role_name}/permissions:all": { "get": { "description": "Retrieves the complete set of effective permissions for a role, including both directly assigned permissions and permissions inherited from base roles through the role hierarchy. Use this endpoint to understand the full scope of capabilities available to users assigned to a specific role. Provide the role name as a path parameter, and the response will include all permissions that apply to the role, accounting for inheritance relationships. This operation is essential for auditing role capabilities, understanding permission inheritance, or verifying the complete access scope before role assignment. Returns a comprehensive list of permission names representing the full set of effective permissions for the specified role.", "tags": [ "Roles" ], "summary": "List effective permissions for role", "operationId": "RolesService_ListEffectiveRolePermissions", "parameters": [ { "schema": { "type": "string" }, "description": "Name of the role", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved effective permissions. Returns the complete list of all permissions that apply to the role, including both direct assignments and inherited permissions from base roles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesListEffectiveRolePermissionsResponse" } } } } } } }, "/api/v1/roles/{role_name}/users:count": { "get": { "description": "Retrieves the total number of users currently assigned to the specified role within the environment. Use this endpoint to monitor role usage, enforce user limits, or understand the scope of role assignments. Provide the role's unique name as a path parameter, and the response will include the current user count for that role. This operation is read-only and does not modify any data or user assignments. The count reflects all users who have the role either directly assigned or inherited through organization membership. This information is useful for capacity planning, security auditing, or understanding the impact of role changes across your user base.", "tags": [ "Roles" ], "summary": "Retrieve user count for role", "operationId": "RolesService_GetRoleUsersCount", "parameters": [ { "schema": { "type": "string" }, "description": "Unique name of the role", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved user count for the specified role. Returns the total number of users currently assigned to the role, including both direct assignments and inherited assignments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesGetRoleUsersCountResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.getRoleUsersCount('admin')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.roles.get_role_users_count(role_name=\"admin\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().GetRoleUsersCount(ctx, \"admin\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "GetRoleUsersCountResponse res = scalekitClient.roles().getRoleUsersCount(\"admin\");" } ] } }, "/api/v1/roles:set_defaults": { "patch": { "description": "Updates the default creator and member roles for the current environment. Use this endpoint to configure which roles are automatically assigned to new users when they join the environment. You can specify role names for both creator and member default roles. The system will validate that the specified roles exist and update the environment settings accordingly. Returns the updated default role objects including their complete role information and permissions.", "tags": [ "Roles" ], "summary": "Set default creator and member roles", "operationId": "RolesService_UpdateDefaultRoles", "responses": { "200": { "description": "Default roles updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateDefaultRolesResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateDefaultRolesRequest" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.role.updateDefaultRoles({\n defaultMemberRole: 'member',\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.roles.roles_pb2 import UpdateDefaultRolesRequest\n\nres = scalekit_client.roles.update_default_roles(\n default_roles=UpdateDefaultRolesRequest(\n default_member_role=\"member\"\n )\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Role().UpdateDefaultRoles(ctx, \"member\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "UpdateDefaultRolesResponse res = scalekitClient.roles().updateDefaultRoles(\n UpdateDefaultRolesRequest.newBuilder()\n .setDefaultMemberRole(\"member\")\n .build()\n);" } ] } }, "/api/v1/sessions/{session_id}": { "get": { "description": "Retrieves comprehensive details for a specific user session including authentication status, device information, and expiration timelines. Use this endpoint to fetch current session metadata for security audits, session validation, or to display session information in user account management interfaces. Returns all session properties including the user ID, authenticated organizations, device details with browser/OS information, IP address and geolocation, and all relevant timestamps (creation, last activity, idle expiration, absolute expiration, and actual expiration if applicable).", "tags": [ "Sessions" ], "summary": "Get session details", "operationId": "SessionService_GetSession", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier for the session. Must start with 'ses_' prefix.", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully retrieved session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sessionsSessionDetails" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.session.getSession('ses_123456789')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.sessions.get_session(session_id=\"ses_123456789\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Session().GetSession(ctx, \"ses_123456789\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "SessionDetails res = scalekitClient.sessions().getSession(\"ses_123456789\");" } ] } }, "/api/v1/sessions/{session_id}/revoke": { "post": { "description": "Immediately invalidates a specific user session by session ID, setting its status to 'revoked'. Once revoked, the session cannot be used for any future API requests or application access. Use this endpoint to implement session-level logout, force a user to reauthenticate on a specific device, or terminate suspicious sessions. The revocation is instantaneous and irreversible. Returns the revoked session details including the session ID, user ID, and the revocation timestamp.", "tags": [ "Sessions" ], "summary": "Revoke user session", "operationId": "SessionService_RevokeSession", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier for the session to revoke. Must start with 'ses_' prefix.", "name": "session_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully revoked the session. Returns the revoked session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sessionsRevokeSessionResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.session.revokeSession('ses_123456789')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.sessions.revoke_session(session_id=\"ses_123456789\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Session().RevokeSession(ctx, \"ses_123456789\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "RevokeSessionResponse res = scalekitClient.sessions().revokeSession(\"ses_123456789\");" } ] } }, "/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." } ] } }, "/api/v1/users": { "get": { "description": "Retrieves a paginated list of all users across your entire environment. Use this endpoint to view all users regardless of their organization memberships. This is useful for administrative purposes, user audits, or when you need to see all users in your Scalekit environment. Supports pagination for large user bases.", "tags": [ "Users" ], "summary": "List all users in environment", "operationId": "UserService_ListUsers", "parameters": [ { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of organizations to return per page. Must be between 10 and 100", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token from the previous response. Use to retrieve the next page of organizations", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "List of users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersListUsersResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.user.listUsers({ pageSize: 100 })" }, { "label": "Python SDK", "lang": "python", "source": "# List all users in the environment\nresponse = scalekit_client.users.list_users(page_size=100)" }, { "label": "Go SDK", "lang": "go", "source": "all, err := scalekitClient.User().ListUsers(ctx, &scalekit.ListUsersOptions{PageSize: 100})" }, { "label": "Java SDK", "lang": "java", "source": "ListUsersRequest lur = ListUsersRequest.newBuilder()\n .setPageSize(100)\n .build();\nListUsersResponse allUsers = scalekitClient.users().listUsers(lur);" } ] } }, "/api/v1/users/{id}": { "get": { "description": "Retrieves all details for a user by system-generated user ID. The response includes organization memberships and user metadata.", "tags": [ "Users" ], "summary": "Get user", "operationId": "UserService_GetUser", "parameters": [ { "schema": { "type": "string" }, "description": "System-generated user ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "User details retrieved successfully. Returns full user object with system-generated fields and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersGetUserResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { user } = await scalekit.user.getUser('usr_123456')" }, { "label": "Python SDK", "lang": "python", "source": "resp = scalekit_client.users.get_user(user_id=\"usr_123456\")\nuser = resp.user" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.User().GetUser(ctx, \"usr_123456\")\nif err != nil {\n // handle error\n}\nuser := resp.User" }, { "label": "Java SDK", "lang": "java", "source": "GetUserResponse resp = scalekitClient.users().getUser(\"usr_123456\");\nUser user = resp.getUser();" } ] }, "delete": { "description": "Permanently removes a user from your environment and deletes all associated data. Use this endpoint when you need to completely remove a user account. This action deletes the user's profile, memberships, and all related data across all organizations. This operation cannot be undone, so use with caution.", "tags": [ "Users" ], "summary": "Delete user permanently", "operationId": "UserService_DeleteUser", "parameters": [ { "schema": { "type": "string" }, "description": "System-generated user ID. Must start with 'usr_' (19-25 characters)", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "User successfully deleted. No content returned", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.user.deleteUser('usr_123')" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.users.delete_user(\"usr_123\")" }, { "label": "Go SDK", "lang": "go", "source": "if err := scalekitClient.User().DeleteUser(ctx, \n \"usr_123\"); err != nil {\n panic(err)\n}" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.users().deleteUser(\"usr_123\");" } ] }, "patch": { "description": "Modifies user account information including profile details, metadata, and external ID. Use this endpoint to update a user's personal information, contact details, or custom metadata. You can update the user's profile, phone number, and metadata fields. Note that fields like user ID, email address, environment ID, and creation time cannot be modified.", "tags": [ "Users" ], "summary": "Update user information", "operationId": "UserService_UpdateUser", "parameters": [ { "schema": { "type": "string" }, "description": "System-generated user ID. Must start with 'usr_' and be 19-25 characters long.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "User updated successfully. Returns the modified user object with updated timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersUpdateUserResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "User fields to update. Only specified fields will be modified. Required fields must be provided if being changed.", "$ref": "#/components/schemas/v1usersUpdateUser", "examples": [ { "firstName": "John", "lastName": "Doe" } ] } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.user.updateUser('usr_123', {\n userProfile: {\n firstName: 'John',\n lastName: 'Smith',\n },\n metadata: {\n department: 'sales',\n },\n})" }, { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.users.users_pb2 import UpdateUser\nfrom scalekit.v1.commons.commons_pb2 import UserProfile\n\nupdate_user = UpdateUser(\n user_profile=UserProfile(\n first_name=\"John\",\n last_name=\"Smith\",\n ),\n metadata={\"department\": \"sales\"},\n)\nresponse = scalekit_client.users.update_user(\"usr_123\", update_user)" }, { "label": "Go SDK", "lang": "go", "source": "upd := &usersv1.UpdateUser{\n UserProfile: &usersv1.UpdateUserProfile{\n FirstName: \"John\",\n LastName: \"Smith\",\n },\n Metadata: map[string]string{\n \"department\": \"sales\",\n },\n}\nscalekitClient.User().UpdateUser(ctx, \"usr_123\", upd)" }, { "label": "Java SDK", "lang": "java", "source": "UpdateUser upd = UpdateUser.newBuilder()\n .setUserProfile(\n UpdateUserProfile.newBuilder()\n .setFirstName(\"John\")\n .setLastName(\"Smith\")\n .build())\n .putMetadata(\"department\", \"sales\")\n .build();\nUpdateUserRequest updReq = UpdateUserRequest.newBuilder()\n .setUser(upd)\n .build();\nscalekitClient.users().updateUser(\"usr_123\", updReq);" } ] } }, "/api/v1/users/{user_id}/sessions": { "get": { "description": "Retrieves a paginated list of all sessions associated with a specific user across all devices and browsers. Use this endpoint to audit user activity, display all active sessions in account management interfaces, or verify user authentication status across devices. Supports filtering by session status (active, expired, revoked, logout) and time range (creation date). Returns session details for each session including device information, IP address, geolocation, and current status. The response includes pagination metadata (page tokens and total count) to handle large session lists efficiently.", "tags": [ "Sessions" ], "summary": "List user sessions", "operationId": "SessionService_GetUserSessions", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier for the user whose sessions to retrieve. Must start with 'usr_' prefix.", "name": "user_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of sessions to return in a single page. Optional parameter. If not specified, defaults to a server-defined limit. Use smaller values for faster responses, larger values for fewer requests.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "Pagination token from the previous response for retrieving the next page of results. Leave empty for the first page. Use the next_page_token from a previous response to fetch subsequent pages.", "name": "page_token", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Filter sessions by one or more status values. Possible values: 'active', 'expired', 'revoked', 'logout'. Leave empty to include all statuses. Multiple values use OR logic (e.g., status=['active', 'expired'] returns sessions that are either active OR expired).", "name": "filter.status", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Filter to include only sessions created on or after this timestamp. Optional. Uses RFC 3339 format. Useful for querying sessions within a specific time window.", "name": "filter.start_time", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Filter to include only sessions created on or before this timestamp. Optional. Uses RFC 3339 format. Must be after start_time if both are specified.", "name": "filter.end_time", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved user sessions. Returns a list of sessions with pagination information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sessionsUserSessionDetails" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "// Basic usage\nconst res = await scalekit.session.getUserSessions('user_123')\n\n// With pagination and filtering\nconst res = await scalekit.session.getUserSessions('user_123', {\n pageSize: 10,\n pageToken: 'next_page_token',\n filter: {\n status: ['ACTIVE'],\n startTime: new Date('2024-01-01'),\n endTime: new Date('2024-12-31'),\n },\n})" }, { "label": "Python SDK", "lang": "python", "source": "# Basic usage\nres = scalekit_client.sessions.get_user_sessions(user_id=\"user_123\")\n\n# With pagination and filtering\nfrom google.protobuf.timestamp_pb2 import Timestamp\nfrom datetime import datetime\n\nstart_time = Timestamp()\nstart_time.FromDatetime(datetime(2024, 1, 1))\nend_time = Timestamp()\nend_time.FromDatetime(datetime(2024, 12, 31))\n\nfilter_obj = scalekit_client.sessions.create_session_filter(\n status=[\"ACTIVE\"], start_time=start_time, end_time=end_time\n)\nres = scalekit_client.sessions.get_user_sessions(\n user_id=\"user_123\", page_size=10, page_token=\"next_page_token\", filter=filter_obj\n)" }, { "label": "Go SDK", "lang": "go", "source": "// Basic usage\nresp, err := scalekitClient.Session().GetUserSessions(ctx, \"user_123\", 0, \"\", nil)\nif err != nil { /* handle err */ }\n\n// With pagination and filtering\n// import \"time\", sessionsv1 \"...\", \"google.golang.org/protobuf/types/known/timestamppb\"\nstartTime, _ := time.Parse(time.RFC3339, \"2024-01-01T00:00:00Z\")\nendTime, _ := time.Parse(time.RFC3339, \"2024-12-31T23:59:59Z\")\nfilter := &sessionsv1.UserSessionFilter{\n Status: []string{\"ACTIVE\"},\n StartTime: timestamppb.New(startTime),\n EndTime: timestamppb.New(endTime),\n}\nresp, err := scalekitClient.Session().GetUserSessions(ctx, \"user_123\", 10, \"next_page_token\", filter)\nif err != nil { /* handle err */ }" }, { "label": "Java SDK", "lang": "java", "source": "// Basic usage\nUserSessionDetails res = scalekitClient.sessions().getUserSessions(\"user_123\", null, null, null);\n\n// With pagination and filtering\n// import UserSessionFilter, Timestamp, Instant\nUserSessionFilter filter = UserSessionFilter.newBuilder()\n .addStatus(\"ACTIVE\")\n .setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse(\"2024-01-01T00:00:00Z\").getEpochSecond()).build())\n .setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse(\"2024-12-31T23:59:59Z\").getEpochSecond()).build())\n .build();\nUserSessionDetails res = scalekitClient.sessions().getUserSessions(\"user_123\", 10, \"next_page_token\", filter);" } ] } }, "/api/v1/users/{user_id}/sessions/revoke": { "post": { "description": "Immediately invalidates all active sessions for a specific user across all devices and browsers, setting their status to 'revoked'. Use this endpoint to implement global logout functionality, force re-authentication after security incidents, or terminate all sessions following a password reset or credential compromise. Only active sessions are revoked; already expired, logout, or previously revoked sessions remain unchanged. The revocation is atomic and instantaneous. Returns a list of all revoked sessions with their details and a total count of sessions revoked.", "tags": [ "Sessions" ], "summary": "Revoke all user sessions", "operationId": "SessionService_RevokeAllUserSessions", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier for the user whose all sessions will be revoked. Must start with 'usr_' prefix.", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successfully revoked all user sessions. Returns the list of revoked sessions and total count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sessionsRevokeAllUserSessionsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.session.revokeAllUserSessions('user_123')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.sessions.revoke_all_user_sessions(user_id=\"user_123\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Session().RevokeAllUserSessions(ctx, \"user_123\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "RevokeAllUserSessionsResponse res = scalekitClient.sessions().revokeAllUserSessions(\"user_123\");" } ] } }, "/api/v1/users:external/{external_id}": { "get": { "description": "Retrieves all details for a user by your application's external identifier. Use this endpoint when you store users in Scalekit using your own system's identifiers and need to retrieve the Scalekit user record. The response includes organization memberships and user metadata.", "tags": [ "Users" ], "summary": "Get user by external ID", "operationId": "UserService_GetUser2", "parameters": [ { "schema": { "type": "string" }, "description": "Your application's unique identifier for this user, used to link Scalekit with your system.", "name": "external_id", "in": "path", "required": true } ], "responses": { "200": { "description": "User details retrieved successfully. Returns full user object with system-generated fields and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersGetUserResponse" } } } } } }, "delete": { "description": "Permanently removes a user identified by your application's external identifier. This action deletes the user's profile, memberships, and all related data across all organizations. This operation cannot be undone.", "tags": [ "Users" ], "summary": "Delete user by external ID", "operationId": "UserService_DeleteUser2", "parameters": [ { "schema": { "type": "string" }, "description": "External system identifier from connected directories. Must match existing records", "name": "external_id", "in": "path", "required": true } ], "responses": { "200": { "description": "User successfully deleted. No content returned", "content": { "application/json": { "schema": {} } } } } }, "patch": { "description": "Modifies user account information for a user identified by your application's external identifier. Use this endpoint to keep user profile data in sync from your system without needing to store Scalekit's internal user ID. You can update the user's profile, phone number, and metadata fields.", "tags": [ "Users" ], "summary": "Update user by external ID", "operationId": "UserService_UpdateUser2", "parameters": [ { "schema": { "type": "string" }, "description": "Your application's unique identifier for this user, used to link Scalekit with your system.", "name": "external_id", "in": "path", "required": true } ], "responses": { "200": { "description": "User updated successfully. Returns the modified user object with updated timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersUpdateUserResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "description": "User fields to update. Only specified fields will be modified. Required fields must be provided if being changed.", "$ref": "#/components/schemas/v1usersUpdateUser", "examples": [ { "firstName": "John", "lastName": "Doe" } ] } } }, "required": true } } }, "/api/v1/users:search": { "get": { "description": "Searches for users across the entire environment by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages.", "tags": [ "Users" ], "summary": "Search users", "operationId": "UserService_SearchUsers", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 100 }, "description": "Search term to match against user email, IDs, or external IDs. Must be at least 3 characters. Case insensitive.", "name": "query", "in": "query", "required": true }, { "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 30 }, "description": "Maximum number of users 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" } ], "responses": { "200": { "description": "Matching users returned; includes pagination cursors for navigating large result sets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersSearchUsersResponse" } } } }, "400": { "description": "Bad Request - query must be at least 3 characters and no more than 100 characters.", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/webauthn/credentials": { "get": { "description": "Retrieves all registered passkeys for the current user, including device information, creation timestamps, and display names. Use this to show users their registered authenticators.", "tags": [ "Passkeys" ], "summary": "List user's passkeys", "operationId": "WebAuthnService_ListCredentials", "parameters": [ { "schema": { "type": "string" }, "description": "User ID to list credentials for (optional, current user if not provided)", "name": "user_id", "in": "query" } ], "responses": { "200": { "description": "List of passkeys with metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webauthnListCredentialsResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.webauthn.listCredentials('user_123')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.webauthn.list_credentials(user_id=\"user_123\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.WebAuthn().ListCredentials(ctx, \"user_123\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "ListCredentialsResponse res = scalekitClient.webAuthn().listCredentials(\"user_123\");" } ] } }, "/api/v1/webauthn/credentials/{credential_id}": { "delete": { "description": "Deletes a specific passkey credential for the current user. After removal, the authenticator can no longer be used for authentication.", "tags": [ "Passkeys" ], "summary": "Remove a passkey", "operationId": "WebAuthnService_DeleteCredential", "parameters": [ { "schema": { "type": "string" }, "description": "The credential ID to delete", "name": "credential_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Passkey successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webauthnDeleteCredentialResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.webauthn.deleteCredential('wac_123')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.webauthn.delete_credential(credential_id=\"wac_123\")" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.WebAuthn().DeleteCredential(ctx, \"wac_123\")\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "DeleteCredentialResponse res = scalekitClient.webAuthn().deleteCredential(\"wac_123\");" } ] }, "patch": { "description": "Updates the display name of a passkey credential to help users identify their authenticators. Only the display name can be modified.", "tags": [ "Passkeys" ], "summary": "Rename a passkey", "operationId": "WebAuthnService_UpdateCredential", "parameters": [ { "schema": { "type": "string" }, "description": "The credential ID to update", "name": "credential_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Passkey successfully updated with new name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webauthnUpdateCredentialResponse" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnServiceUpdateCredentialBody" } } }, "required": true }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.webauthn.updateCredential('wac_123', 'Work Laptop Passkey')" }, { "label": "Python SDK", "lang": "python", "source": "res = scalekit_client.webauthn.update_credential(\n credential_id=\"wac_123\",\n display_name=\"Work Laptop Passkey\"\n)" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.WebAuthn().UpdateCredential(\n ctx,\n \"wac_123\",\n \"Work Laptop Passkey\",\n)\nif err != nil { /* handle err */ }\n_ = resp" }, { "label": "Java SDK", "lang": "java", "source": "UpdateCredentialResponse res = scalekitClient.webAuthn()\n .updateCredential(\"wac_123\", \"Work Laptop Passkey\");" } ] } }, "/api/v1/connections/{connection_id}/trigger-ingress": { "get": { "description": "Retrieves the webhook URL a provider sends this connection's events to, and the state of its signing secret. Use this endpoint while setting up a webhook trigger: paste the URL into the provider's app configuration, and check whether a signing secret is set and whether a rotation is in progress. Pass the connection ID in the path. This endpoint never creates a URL; create one first with CreateTriggerIngressEndpoint. The signing secret itself is never returned. Returns the endpoint ID, the URL, whether a signing secret is set, a masked form of the secret showing at most its last four characters, and the rotation state, including signing_secret_rotation_id to pass to ConfirmTriggerSigningSecretRotation.", "tags": [ "Triggers" ], "summary": "Get a connection's webhook URL", "operationId": "TriggerService_GetTriggerIngressEndpoint", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The connection's webhook URL, its masked signing-secret state, and any rotation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersTriggerIngressEndpoint" } } } }, "400": { "description": "Invalid request - connection_id is not a valid connection ID", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no webhook URL has been created for this connection yet (error_code TRIGGER_INGRESS_ENDPOINT_NOT_CREATED; call CreateTriggerIngressEndpoint), the connection does not exist in this environment (error_code RESOURCE_NOT_FOUND), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND)", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the webhook URL or its signing-secret state could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } }, "post": { "description": "Creates the webhook URL a provider sends this connection's events to. Use this endpoint once per connection when you set up a webhook trigger: paste the returned URL into the provider's app configuration, then store the provider's signing secret with SetTriggerSigningSecret. Pass the connection ID in the path; the request has no body. Only a connection whose provider publishes at least one webhook trigger can have a webhook URL. The call is idempotent: when the connection already has a URL, that URL is returned unchanged, so a retry never replaces a URL already registered with the provider. The URL accepts request bodies up to 1 MB. Returns the endpoint ID, the URL and the signing-secret state; the signing secret itself is never returned.", "tags": [ "Triggers" ], "summary": "Create a connection's webhook URL", "operationId": "TriggerService_CreateTriggerIngressEndpoint", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The newly created webhook URL, or the connection's existing one unchanged, with its signing-secret state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersTriggerIngressEndpoint" } } } }, "400": { "description": "Invalid request, nothing created - connection_id is not a valid connection ID; the connection's provider publishes no webhook trigger, so it has no use for a webhook URL (error_code TRIGGER_INGRESS_NOT_APPLICABLE); or the provider's webhook trigger definitions are temporarily unavailable (error_code TRIGGER_INGRESS_DEFINITIONS_UNAVAILABLE)", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the connection does not exist in this environment, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the webhook URL could not be created or read back; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connections/{connection_id}/trigger-ingress/signing-secret": { "put": { "description": "Stores the secret the provider signs its webhook events with, so events sent to the connection's webhook URL can be verified. Use this endpoint after CreateTriggerIngressEndpoint, with the signing secret copied from the provider's app configuration, and again whenever the provider's secret changes. Pass the connection ID in the path and signing_secret in the body; leading and trailing whitespace is removed before the secret is stored. A provider that sends no signature of its own takes a Scalekit-generated secret from GenerateTriggerSigningSecret instead, and is refused here. Until a secret is set, the webhook URL asks the provider to retry every event instead of accepting it. When a secret is already stored, setting a different one starts a rotation: both secrets are accepted until you confirm the rotation with ConfirmTriggerSigningSecretRotation, or for at most 24 hours. Sending the secret that is already stored changes nothing. Returns the endpoint with its masked secret and rotation state, including the signing_secret_rotation_id to confirm; the secret itself is never returned.", "tags": [ "Triggers" ], "summary": "Set a connection's webhook signing secret", "operationId": "TriggerService_SetTriggerSigningSecret", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The secret is stored; the endpoint's masked secret and rotation state, including whether a rotation is now in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersTriggerIngressEndpoint" } } } }, "400": { "description": "Invalid request, nothing written - connection_id is not a valid connection ID; signing_secret is shorter than 8 characters once leading and trailing whitespace is removed, or longer than 4096 characters; the connection's provider sends no signature of its own, so its secret is generated by Scalekit rather than set (error_code TRIGGER_SIGNING_SECRET_GENERATED_ONLY; call GenerateTriggerSigningSecret instead); or the provider's webhook trigger definitions are temporarily unavailable (error_code TRIGGER_INGRESS_DEFINITIONS_UNAVAILABLE)", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no webhook URL has been created for this connection yet (error_code TRIGGER_INGRESS_ENDPOINT_NOT_CREATED; call CreateTriggerIngressEndpoint first), the connection does not exist in this environment (error_code RESOURCE_NOT_FOUND), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND)", "content": { "application/json": { "schema": {} } } }, "409": { "description": "Conflict - a rotation is already in progress. Confirm it with ConfirmTriggerSigningSecretRotation, or wait for the previous secret's expiry, before setting another secret", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the signing secret could not be stored; retry the request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceSetTriggerSigningSecretBody" } } }, "required": true } } }, "/api/v1/connections/{connection_id}/trigger-ingress/signing-secret/confirm": { "post": { "description": "Ends a signing-secret rotation by retiring the previous secret, so only the current secret is accepted. Call this endpoint once the provider's app configuration holds the new secret. A rotation is never confirmed automatically: until you call this endpoint, the previous secret stays accepted until its expiry, at most 24 hours after the rotation started. Pass the connection ID in the path, and in the body the signing_secret_rotation_id from the latest SetTriggerSigningSecret or GetTriggerIngressEndpoint response, so that only the rotation you looked at is confirmed. Calling this endpoint when no rotation is in progress succeeds and changes nothing. Returns the endpoint with its masked secret and rotation state.", "tags": [ "Triggers" ], "summary": "Confirm a signing secret rotation", "operationId": "TriggerService_ConfirmTriggerSigningSecretRotation", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The previous secret is retired, or no rotation was in progress; the endpoint's current signing-secret state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersTriggerIngressEndpoint" } } } }, "400": { "description": "Invalid request - connection_id is not a valid connection ID, or a rotation is in progress and signing_secret_rotation_id is missing or does not match it, for example because a newer rotation has started. The message names the current rotation ID; read the endpoint again with GetTriggerIngressEndpoint before confirming", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no webhook URL has been created for this connection yet (error_code TRIGGER_INGRESS_ENDPOINT_NOT_CREATED; call CreateTriggerIngressEndpoint first), the connection does not exist in this environment (error_code RESOURCE_NOT_FOUND), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND)", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the rotation could not be confirmed; retry the request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceConfirmTriggerSigningSecretRotationBody" } } }, "required": true } } }, "/api/v1/connections/{connection_id}/trigger-ingress/signing-secret/generate": { "post": { "description": "Generates a random signing secret for a connection's webhook URL, stores it, and returns it in plain text together with the URL that carries it. Use this endpoint for a provider that sends no signature of its own (provides_bearer_secret is true on its triggers), after CreateTriggerIngressEndpoint. Pass the connection ID in the path; the body is empty. The provider presents the secret back on every event, in an `Authorization: Bearer ` header, the `X-Scalekit-Webhook-Secret` header, or the final path segment of url_with_secret, and an event without it is rejected. The first call on an endpoint with no secret sets one. A call where a secret already exists starts a rotation rather than replacing it, exactly as SetTriggerSigningSecret does: both secrets are accepted until you confirm the rotation with ConfirmTriggerSigningSecretRotation, or for at most 24 hours. A provider that signs its own events takes its secret from its app configuration through SetTriggerSigningSecret instead, and is refused here. Returns the secret in plain text, url_with_secret, and the endpoint with its masked secret and rotation state. The plain-text secret appears only in this response and is never returned again; generate another if it is lost.", "tags": [ "Triggers" ], "summary": "Generate a connection's signing secret", "operationId": "TriggerService_GenerateTriggerSigningSecret", "parameters": [ { "schema": { "type": "string" }, "description": "The connection whose webhook URL receives the generated secret. Between 1 and 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The generated secret in plain text, the webhook URL with the secret appended, and the endpoint's state, including whether a rotation is now in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersGenerateTriggerSigningSecretResponse" } } } }, "400": { "description": "Invalid request, nothing written - connection_id is not a valid connection ID; the connection's provider signs its own events, so its secret is copied from the provider's app configuration and stored with SetTriggerSigningSecret instead (error_code TRIGGER_SIGNING_SECRET_NOT_GENERATABLE); or the provider's webhook trigger definitions are temporarily unavailable (error_code TRIGGER_INGRESS_DEFINITIONS_UNAVAILABLE)", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no webhook URL has been created for this connection yet (error_code TRIGGER_INGRESS_ENDPOINT_NOT_CREATED; call CreateTriggerIngressEndpoint first), the connection does not exist in this environment (error_code RESOURCE_NOT_FOUND), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND)", "content": { "application/json": { "schema": {} } } }, "409": { "description": "Conflict - a rotation is already in progress. Confirm it with ConfirmTriggerSigningSecretRotation, or wait for the previous secret's expiry, before generating another secret", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the secret could not be generated or stored, or the endpoint could not be read back; retry the request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceGenerateTriggerSigningSecretBody" } } }, "required": true } } }, "/api/v1/connections/{connection_id}/trigger-subscriptions": { "get": { "description": "Lists the trigger subscriptions on a connection, newest first. Use this endpoint to show which accounts are subscribed to which triggers, and to check whether each subscription is delivering. Pass the connection ID in the path. Filter by trigger_name and statuses, and page with page_size and page_token. For a polled trigger, each subscription returns both the interval you requested and the interval it actually runs at, which can be slower when the environment's polling budget is shared across many subscriptions. A polled subscription also returns its poll state: when it last ran, why the last run failed, and whether polling is backed off. Returns one page of subscriptions, the next and previous page tokens, total_size, and status_counts, which counts subscriptions per status across every page.", "tags": [ "Triggers" ], "summary": "List trigger subscriptions on a connection", "operationId": "TriggerService_ListTriggerSubscriptions", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Narrows the list to one trigger's subscriptions. Omit it to list every subscription on the connection.", "name": "trigger_name", "in": "query" }, { "schema": { "type": "array", "items": { "enum": [ "ACTIVE", "THROTTLED", "PAUSED", "PAUSED_CREDENTIAL" ], "type": "string" } }, "style": "form", "explode": true, "description": "Narrows the list to subscriptions in these statuses, at most 4. Omit it for every status; TRIGGER_SUBSCRIPTION_STATUS_UNSPECIFIED is refused. Does not affect status_counts, so a client filtering to one status still sees the totals for all of them.\n\n - ACTIVE: Delivering. For a polled trigger, at the requested interval.\n - THROTTLED: Running slower than requested, not stopped. Still delivering.\n - PAUSED: Stopped by the customer.\n - PAUSED_CREDENTIAL: Stopped because the account's credential no longer\nworks. Distinct from PAUSED so the two have distinguishable explanations for missing events.", "name": "statuses", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "How many subscriptions to return. Defaults to 10; a larger value than 100 is capped at 100 rather than refused.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "The next_page_token or prev_page_token from a previous response. Omit it to read the first page. A value that is not a token from a previous response is refused with 400.", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "One page of the connection's trigger subscriptions, plus page tokens, the total match count and per-status counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersListTriggerSubscriptionsResponse" } } } }, "400": { "description": "Invalid request - connection_id is not a valid connection ID, page_token is not a token from a previous response, or statuses holds TRIGGER_SUBSCRIPTION_STATUS_UNSPECIFIED or an unknown status", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the connection does not exist in this environment, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the subscriptions could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } }, "post": { "description": "Creates a subscription to one trigger, either for one connected account or for the whole connection. Use this endpoint after ListAvailableTriggers and ListEligibleAccounts have shown that the trigger and account can be used. Pass the connection ID in the path, and trigger_name in the body. For an account-scoped trigger, pass connected_account_id; for a connection-scoped trigger, omit it. Use config to set the trigger's filter values, with keys spelled exactly as the trigger's config_fields declare them. For a polled trigger, interval_seconds sets the polling interval, and defaults to the trigger's default interval. An interval below the trigger's minimum is refused, not rounded up. Each refusal says what to change, for example the missing scope, the minimum interval, or that the account was authorized under a different app. Returns the new subscription with its status, its requested and effective intervals, and the account's health for this trigger.", "tags": [ "Triggers" ], "summary": "Subscribe to a trigger", "operationId": "TriggerService_CreateTriggerSubscription", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The created subscription, including its status, intervals, filter values and the subscribed account's health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersTriggerSubscription" } } } }, "400": { "description": "Invalid request - the message names what to change. Returned when an ID is malformed; config holds an unknown key, misses a required key, or holds a value longer than 512 characters; interval_seconds is below the trigger's minimum, or is set for a webhook trigger; connected_account_id is missing for an account-scoped trigger, or present for a connection-scoped one; the trigger polls and is connection-scoped, which is not supported; or the account cannot receive the trigger because its grant lacks a required scope or the bot install the trigger needs, it was authorized under a different app, the trigger needs your own provider app, its provider workspace or user is not yet confirmed, or it holds no usable credential", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the connection or connected account does not exist in this environment, the connected account belongs to a different connection, the connection's provider publishes no trigger with this name, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "409": { "description": "Conflict - this account, or this connection for a connection-scoped trigger, already has a subscription to this trigger with exactly these config values", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the subscription could not be created; nothing was created", "content": { "application/json": { "schema": {} } } }, "503": { "description": "Service unavailable - polling for the new subscription could not be scheduled, so the subscription was not created; retry the same request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceCreateTriggerSubscriptionBody" } } }, "required": true } } }, "/api/v1/connections/{connection_id}/trigger-subscriptions/{subscription_id}": { "delete": { "description": "Deletes a trigger subscription from a connection. Use this endpoint when an account or connection should stop receiving a trigger's events. Pass the connection ID and the subscription ID in the path; the subscription must belong to that connection. New events no longer match the subscription, and a polled subscription stops polling. Events already handed off for delivery before the delete are not affected. The delete is permanent; to receive the trigger again, create a new subscription. Returns an empty body.", "tags": [ "Triggers" ], "summary": "Delete a trigger subscription", "operationId": "TriggerService_DeleteTriggerSubscription", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "ID of the trigger subscription to delete. It must belong to the connection named in the path.", "name": "subscription_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The subscription was deleted; empty body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/protobufEmpty" } } } }, "400": { "description": "Invalid request - connection_id is not a valid connection ID, or subscription_id is not a valid trigger subscription ID", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no subscription with this ID exists on this connection in this environment, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the subscription could not be deleted; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connections/{connection_id}/trigger-subscriptions:batchCreate": { "post": { "description": "Subscribes many connected accounts to one trigger with one filter, and reports what happened to each account separately. Use this instead of repeating the single-account call when onboarding a connection that already has many accounts. The call is best-effort rather than all-or-nothing: a refused account does not undo one that succeeded, because refusals here are ordinary rather than exceptional — an account may hold a revoked credential, lack a scope, or already carry this exact filter. Each result names its own outcome, and a refusal names its remedy. Retrying the whole request is safe: an account subscribed by an earlier attempt comes back as already subscribed rather than as an error. A connection-scoped trigger is subscribed on the connection itself rather than per account: send an empty connected_account_ids for it, and the one subscription comes back as a single result with an empty connected_account_id.", "tags": [ "Triggers" ], "summary": "Subscribe several accounts to a trigger", "operationId": "TriggerService_BatchCreateTriggerSubscriptions", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "One result per requested account, in request order, and the number of subscriptions this call created. Individual accounts can still be REFUSED, NOT_FOUND or FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersBatchCreateTriggerSubscriptionsResponse" } } } }, "400": { "description": "Invalid request, nothing created - connection_id or an entry of connected_account_ids is malformed; config is invalid for this trigger; interval_seconds is below the trigger's minimum, or is set for a webhook trigger; the trigger polls and is connection-scoped, which is not supported; or connected_account_ids is empty for a trigger that is subscribed per connected account. A well-formed ID naming an account that does not exist is not this case: it comes back as a per-account NOT_FOUND result with a 200, so one bad ID in a batch of a hundred does not discard the ninety-nine that would have succeeded", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the connection does not exist in this environment, the connection's provider publishes no trigger with this name, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the connection or the trigger's definition could not be read, so no account was processed; retry the request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceBatchCreateTriggerSubscriptionsBody" } } }, "required": true } } }, "/api/v1/connections/{connection_id}/trigger-subscriptions:batchDelete": { "post": { "description": "Deletes many trigger subscriptions on one connection, and reports what happened to each one separately. Use this endpoint to unsubscribe a selection from the subscription list, or every subscription a set of connected accounts holds to one trigger, instead of calling DeleteTriggerSubscription once per subscription. Pass the connection ID in the path, and name the subscriptions in the body in exactly one of two ways: by `subscription_ids`, or by `trigger_name` together with `connected_account_ids`, which deletes every subscription those accounts hold to that trigger on this connection, whatever its filter. `trigger_name` alone is refused, so no request can delete every subscription to a trigger. The call is best-effort rather than all-or-nothing: a subscription that could not be deleted does not bring back one that was. Retrying the whole request is safe: a subscription deleted by an earlier attempt comes back as NOT_FOUND, so treat DELETED and NOT_FOUND alike as gone. Unlike DeleteTriggerSubscription, which answers 404 for a missing subscription, the batch reports it as one NOT_FOUND result among many. Delivery stops for each deleted subscription exactly as with DeleteTriggerSubscription: an event already handed off for delivery is still delivered. Returns one result per subscription, each with its outcome (DELETED, NOT_FOUND, FAILED, or NOT_ATTEMPTED when the request ran out of time before reaching it) and a reason, plus deleted_count.", "tags": [ "Triggers" ], "summary": "Delete several trigger subscriptions", "operationId": "TriggerService_BatchDeleteTriggerSubscriptions", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection whose subscriptions to delete. Only subscriptions on this connection are deleted: a subscription ID from another connection comes back as NOT_FOUND.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Request processed; every subscription ID, or every subscription found for the named accounts, has its own result in results, and deleted_count says how many subscriptions this call deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersBatchDeleteTriggerSubscriptionsResponse" } } } }, "400": { "description": "Invalid request, nothing deleted - both selectors or neither were sent, or `trigger_name` and `connected_account_ids` were not sent together; a list holds more than 100 IDs or repeats one, including two spellings of the same ID; `connection_id` is not a valid connection ID, an entry of `subscription_ids` is not a trigger subscription ID (`trgs_`), or an entry of `connected_account_ids` is not a connected account ID (`ca_`); or the named accounts hold more than 1000 subscriptions to the trigger, so fewer `connected_account_ids` must be sent per request. A well-formed ID naming a subscription that does not exist, was already deleted, or belongs to another connection is not this case: it comes back as a NOT_FOUND result with a 200, so one stale ID does not discard the rest of the batch.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - Triggers is not enabled for the environment, or `connection_id` can never name a connection. Nothing was deleted. A missing subscription is not this case: it is a NOT_FOUND result with a 200.", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - this environment has sent too many batch delete requests in the last minute. Nothing was deleted; retry after a short wait.", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the subscriptions that `trigger_name` and `connected_account_ids` name could not be read, so nothing was deleted. Only that selector fails this way; retrying is safe.", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceBatchDeleteTriggerSubscriptionsBody" } } }, "required": true } } }, "/api/v1/connections/{connection_id}/triggers": { "get": { "description": "Lists every trigger the connection's provider publishes, and marks each one as available or unavailable on this connection. Use this endpoint to build a trigger picker, or to find out what a trigger needs before you subscribe to it. Pass the connection ID in the path. A trigger that cannot run on this connection is still returned, with available set to false and a reason, a remedy and, where one applies, a refusal_code. For example, a trigger that needs your own provider app is unavailable while the connection uses Scalekit's shared app. Each trigger describes how it detects events (webhook or poll), its required scopes, its configuration fields, its polling intervals, and whether it needs a signing secret. The response also states whether the connection uses Scalekit's shared provider app. Next, call ListEligibleAccounts to see which connected accounts can receive a trigger.", "tags": [ "Triggers" ], "summary": "List triggers available on a connection", "operationId": "TriggerService_ListAvailableTriggers", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The provider's triggers, each with its availability on this connection, and whether the connection uses Scalekit's shared provider app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersListAvailableTriggersResponse" } } } }, "400": { "description": "Invalid request - connection_id is not a valid connection ID", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the connection does not exist in this environment, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the triggers for this connection could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/connections/{connection_id}/triggers/{trigger_name}/eligible-accounts": { "get": { "description": "Lists the connected accounts on a connection, and marks each one as eligible or ineligible for one trigger. Use this endpoint to choose which accounts to subscribe, before calling CreateTriggerSubscription or BatchCreateTriggerSubscriptions. Pass the connection ID and the trigger name in the path. Use query to search account identifiers, and page_size and page_token to page through the results. An ineligible account is returned with a reason and a remedy instead of being left out, so you can see why an account is refused. Each account also carries its health for this trigger: a state, and the single action that resolves it. Returns one page of accounts, the next and previous page tokens, and total_size, which counts the accounts on this connection that match the query.", "tags": [ "Triggers" ], "summary": "List accounts eligible for a trigger", "operationId": "TriggerService_ListEligibleAccounts", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the connection, in this environment. Up to 64 characters.", "name": "connection_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Name of the trigger, as returned in the name field of ListAvailableTriggers. Up to 128 characters.", "name": "trigger_name", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Narrows the list to accounts whose identifier contains this text, case-insensitively. Matched against every account on the connection, not only the current page. Up to 100 characters.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "format": "int64" }, "description": "How many accounts to return. Defaults to 10; a larger value than 100 is capped at 100 rather than refused.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "The next_page_token or prev_page_token from a previous response. Omit it to read the first page. A value that is not a token from a previous response is refused with 400.", "name": "page_token", "in": "query" } ], "responses": { "200": { "description": "One page of the connection's accounts, each with its eligibility and health for the trigger, plus page tokens and the total match count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersListEligibleAccountsResponse" } } } }, "400": { "description": "Invalid request - connection_id is not a valid connection ID, page_token is not a token from a previous response, or query is longer than 100 characters", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the connection does not exist in this environment, the connection's provider publishes no trigger with this name, or Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the accounts for this trigger could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/trigger-activity": { "get": { "description": "Returns counts of what happened to the environment's trigger events over the last 24 hours, grouped by outcome. Use this endpoint to diagnose a trigger that did not fire: the counts tell apart events that never arrived, events that arrived and matched no subscription filter, events for a provider workspace that no connected account holds, events that failed signature verification, and events whose handoff for delivery failed. The endpoint takes no parameters and covers every connection in the environment. Counts are aggregates only: no record of an individual event is kept, so no endpoint can explain what happened to one specific event. Returns the counts, the window they cover in hours, whether most recent arrivals failed signature verification, whether the counts are incomplete, and the dashboard path where delivery attempts can be inspected.", "tags": [ "Triggers" ], "summary": "Get trigger event counts for the environment", "operationId": "TriggerService_GetTriggerActivity", "responses": { "200": { "description": "Event counts per outcome for the last 24 hours, with the signature-failure and incomplete-data indicators", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersGetTriggerActivityResponse" } } } }, "404": { "description": "Not found - Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the activity counts could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/trigger-delivery/deliveries/{id}": { "get": { "description": "Finds one trigger event by its message ID or its event ID, and returns every delivery attempt made for it across every delivery endpoint in this environment, oldest first. Use this endpoint when you hold an ID from your own server: the message ID arrives as the `webhook-id` header, and the event ID is the payload's `dedupe_key`. Pass the ID in the path. Attempt IDs (`atmpt_`) are not accepted. Only this environment's deliveries are searched, so an ID from another environment is reported as not found. Returns the event's message ID, event ID and creation time, the trigger subscription, trigger and connection it came from while they still exist, and its attempts, each naming the endpoint and URL it was sent to, with response bodies cut to their first 4096 bytes. Returns at most 50 attempts, the newest 50; `truncated` is true when the event has more. The event payload is never returned.", "tags": [ "Triggers" ], "summary": "Find a trigger delivery by ID", "operationId": "TriggerService_LookupTriggerDelivery", "parameters": [ { "schema": { "type": "string" }, "description": "The message ID (`msg_…`, sent to the endpoint as the `webhook-id` header) or the event ID (the payload's `dedupe_key`) of the trigger event to find. 1 to 256 characters: letters, digits, `.`, `_` and `-`. An attempt ID (`atmpt_…`) is refused.", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "The event, with its message ID, event ID and creation time, the trigger and connection it came from, and its delivery attempts to every endpoint, oldest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersLookupTriggerDeliveryResponse" } } } }, "400": { "description": "Invalid request - id is empty, longer than 256 characters, contains characters other than letters, digits, `.`, `_` and `-`, or is an attempt ID (`atmpt_`)", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - no trigger event with this message ID or event ID exists in this environment (error_code NOT_FOUND), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND)", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - deliveries are being read too often. Retry shortly; the request is not retried on your behalf", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the delivery could not be looked up; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/trigger-delivery/deliveries:batchLookup": { "post": { "description": "Finds up to 25 trigger events by message ID or event ID, and returns each one's delivery attempts across every delivery endpoint in this environment, as LookupTriggerDelivery does for one. Use this endpoint when you hold a list of IDs from your own server, for example to check which of a day's events reached you. Pass the IDs in the body, in any mix of message IDs and event IDs. Attempts in a batch result carry no response body; look one delivery up with LookupTriggerDelivery to read the bodies. Only this environment's deliveries are searched, so an ID from another environment comes back as NOT_FOUND. When reads are refused for volume partway through, that ID comes back RATE_LIMITED and the batch stops: IDs not yet looked up come back NOT_ATTEMPTED, to be sent again shortly. The call only reads, so retrying the whole request is always safe. Returns one result per ID, in the order sent, each with its outcome (FOUND with the delivery, NOT_FOUND, RATE_LIMITED, FAILED or NOT_ATTEMPTED) and a reason, plus found_count. The event payload is never returned.", "tags": [ "Triggers" ], "summary": "Find several trigger deliveries by ID", "operationId": "TriggerService_BatchLookupTriggerDeliveries", "responses": { "200": { "description": "Request processed; every ID has its own result in results, in the order sent, and found_count says how many were found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersBatchLookupTriggerDeliveriesResponse" } } } }, "400": { "description": "Invalid request, nothing looked up - `ids` is empty, holds more than 25 IDs or repeats one; an ID is longer than 256 characters or contains characters other than letters, digits, `.`, `_` and `-`; or an ID is an attempt ID (`atmpt_`), which LookupTriggerDelivery refuses too. A well-formed ID that names no trigger event in this environment is not this case: it comes back as a NOT_FOUND result with a 200", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - Triggers is not enabled for the environment. An ID that names no trigger event is not this case: it is a NOT_FOUND result with a 200", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - this environment has sent too many batch lookup requests in the last minute. Nothing was looked up; retry after a short wait. Reads refused for volume partway through a batch are not this case: they are reported per ID as RATE_LIMITED, with a 200", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the environment's trigger deliveries could not be reached, so nothing was looked up; retry the request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersBatchLookupTriggerDeliveriesRequest" } } }, "required": true } } }, "/api/v1/trigger-delivery/deliveries:batchResend": { "post": { "description": "Queues a new delivery attempt for up to 50 trigger events, each to one delivery endpoint, and reports what happened to each target separately. Use this to retry deliveries that failed, for example a selection from ListTriggerDeliveriesByEndpoint, instead of resending them one at a time. Pass the targets in the body; each names a message ID and the endpoint to deliver that event to again. QUEUED means a new manual attempt was accepted for delivery, not that the event was delivered: the attempt and its outcome appear in ListTriggerDeliveryAttemptsByMessage as a TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_MANUAL attempt. The call is best-effort: a target that fails does not undo one that was queued. Resending is not idempotent: each time a target is sent it queues one more attempt, so after a partial failure retry only the targets that came back RATE_LIMITED, FAILED or NOT_ATTEMPTED, never the whole request. A FAILED target whose request timed out may still have been queued, so retrying it can queue a second attempt. A FAILED target whose event payload is no longer stored can never be resent; its reason says so. When a target is rate limited the batch stops: targets not yet started come back NOT_ATTEMPTED, while a target already in flight finishes with its own outcome. Returns one result per target, in the order sent, each with its outcome and a reason, plus queued_count. The event payload is never returned.", "tags": [ "Triggers" ], "summary": "Resend several trigger deliveries", "operationId": "TriggerService_BatchResendTriggerDeliveries", "responses": { "200": { "description": "Request processed; every target has its own result in results, in the order sent, and queued_count says how many new attempts this call queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersBatchResendTriggerDeliveriesResponse" } } } }, "400": { "description": "Invalid request, nothing queued - `targets` is empty or holds more than 50; a `msg_id` is not a message ID (`msg_` followed by 1 to 64 letters or digits) or an `endpoint_id` is not an endpoint ID (`ep_` followed by 1 to 64 letters or digits); or the same `msg_id` and `endpoint_id` pair appears twice, since sending it twice would queue two attempts. A well-formed message or endpoint ID that does not exist in this environment is not this case: it comes back as a NOT_FOUND result with a 200", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - Triggers is not enabled for the environment. Nothing was queued. A message or endpoint that does not exist is not this case: it is a NOT_FOUND result with a 200", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - this environment has sent too many batch resend requests in the last minute. Nothing was queued; retry after a short wait. A rate limit reached partway through a batch is not this case: it is reported per target as RATE_LIMITED, with a 200", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the environment's trigger deliveries could not be reached, so nothing was queued; retry the request", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersBatchResendTriggerDeliveriesRequest" } } }, "description": "The deliveries to retry. A repeated msg_id and endpoint_id pair is refused by the service:\nunique cannot be declared on a list of messages, and sending the pair twice would queue two\nattempts.", "required": true } } }, "/api/v1/trigger-delivery/endpoints/{endpoint_id}/attempts": { "get": { "description": "Lists the most recent attempts to deliver trigger events to one of the environment's trigger delivery endpoints, newest first. Use this endpoint to check whether trigger events reached your endpoint, and to inspect the HTTP status and response body each attempt received. Pass the delivery endpoint ID in the path, and optionally page_size, which defaults to 20 and is capped at 100. Only the most recent attempts are returned; there is no page token for older attempts. A failed attempt is retried, so check the newest attempt for a message before concluding it was not delivered. Returns the attempts, each with its status, the HTTP status code and response body your endpoint returned, the message ID, and the time of the attempt.", "tags": [ "Triggers" ], "summary": "List delivery attempts for a trigger endpoint", "operationId": "TriggerService_ListTriggerDeliveryAttemptsByEndpoint", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the trigger delivery endpoint to list attempts for. Must be one of this environment's trigger delivery endpoints.", "name": "endpoint_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of attempts to return, newest first. Defaults to 20 when omitted or zero; a larger value than 100 is capped at 100 rather than refused.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "The endpoint's most recent delivery attempts, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersListTriggerDeliveryAttemptsByEndpointResponse" } } } }, "400": { "description": "Invalid request - endpoint_id is missing, is longer than 256 characters or contains characters other than letters, digits, `.`, `_` and `-`, or does not name a trigger delivery endpoint in this environment", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the delivery attempts could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/trigger-delivery/endpoints/{endpoint_id}/deliveries": { "get": { "description": "Lists one page of the trigger events delivered to one delivery endpoint, newest first, with one entry per event however many attempts it took. Use this endpoint to check whether fired triggers reached your endpoint, and to find the deliveries that failed or are still being retried. Pass the delivery endpoint ID in the path. Narrow the list by delivery state (`status`), by the connection or trigger subscription the event came from (`channel`), and by time (`after`, `before`); `page_size` defaults to 20 and is capped at 100. Deliveries are kept for 90 days, so a time range reaching further back is cut to that window, and a range wholly outside it returns an empty page. Pass `next_page_token` back as `page_token`, with the same endpoint and filters, to read older deliveries. Each delivery returns its message ID, event ID, state and, while it is being retried, the time of its next attempt, and names the trigger subscription, trigger, detection mode and connection it came from while they still exist. Read the attempts behind one delivery with ListTriggerDeliveryAttemptsByMessage. The event payload is never returned.", "tags": [ "Triggers" ], "summary": "List trigger deliveries to an endpoint", "operationId": "TriggerService_ListTriggerDeliveriesByEndpoint", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the trigger delivery endpoint to list deliveries for. 1-256 characters.", "name": "endpoint_id", "in": "path", "required": true }, { "schema": { "type": "integer", "format": "int64" }, "description": "Maximum number of deliveries to return, newest first. Defaults to 20 when omitted or zero; a larger value than 100 is capped at 100 rather than refused.", "name": "page_size", "in": "query" }, { "schema": { "type": "string" }, "description": "The next_page_token from a previous response, to read the next page of older deliveries. Omit it to read the newest page. A token is bound to the environment, the endpoint and the filters it was issued with: a token sent with a different endpoint or different filters is refused rather than mixing two result sets. At most 1024 characters.", "name": "page_token", "in": "query" }, { "schema": { "type": "string", "enum": [ "TRIGGER_DELIVERY_STATUS_DELIVERED", "TRIGGER_DELIVERY_STATUS_PENDING", "TRIGGER_DELIVERY_STATUS_FAILED", "TRIGGER_DELIVERY_STATUS_RETRYING" ] }, "description": "Narrows the list to deliveries in this state. Omit it, or send TRIGGER_DELIVERY_STATUS_UNSPECIFIED, for every state.\n\n - TRIGGER_DELIVERY_STATUS_DELIVERED: An attempt succeeded. No further\nattempt is made.\n - TRIGGER_DELIVERY_STATUS_PENDING: Accepted for delivery; no attempt\nhas finished yet.\n - TRIGGER_DELIVERY_STATUS_FAILED: Every scheduled attempt failed. No\nfurther attempt is made unless one is started by hand.\n - TRIGGER_DELIVERY_STATUS_RETRYING: An attempt failed and another is\nscheduled, at next_attempt_at.", "name": "status", "in": "query" }, { "schema": { "type": "string" }, "description": "Narrows the list to deliveries of events from one connection (a `conn_` ID) or one trigger subscription (a `trgs_` ID). The ID must exist in this environment; any other value is refused with 400. At most 64 characters.", "name": "channel", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Only deliveries of events created after this instant. Omit it to read back to the oldest retained delivery. Deliveries are kept for 90 days, so a value earlier than that is moved forward to the start of the retained window. Refused when later than `before`. Read to the second.", "name": "after", "in": "query" }, { "schema": { "type": "string", "format": "date-time" }, "description": "Only deliveries of events created before this instant. Omit it to start from the newest delivery. A value later than the current time is treated as the current time. With `after`, reads a time range; the list stays newest first within it. Read to the second.", "name": "before", "in": "query" } ], "responses": { "200": { "description": "One page of the endpoint's deliveries, newest first, with a next_page_token when older deliveries exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersListTriggerDeliveriesByEndpointResponse" } } } }, "400": { "description": "Invalid request - endpoint_id is missing, is longer than 256 characters, contains characters other than letters, digits, `.`, `_` and `-`, or does not name a trigger delivery endpoint in this environment; status is not a known delivery status; channel is not a connection ID (`conn_`) or trigger subscription ID (`trgs_`) in this environment; `after` or `before` is not a valid timestamp, or `after` is later than `before`; or page_token is malformed or was issued for a different endpoint or set of filters", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - deliveries are being read too often. Retry shortly; the request is not retried on your behalf", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the deliveries could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/trigger-delivery/endpoints/{endpoint_id}/deliveries/{msg_id}/attempts": { "get": { "description": "Lists every attempt made to deliver one trigger event to one delivery endpoint, oldest first: the first attempt, each automatic retry, and any manual retry. Use this endpoint to show how one delivery from ListTriggerDeliveriesByEndpoint went, attempt by attempt. Pass the delivery endpoint ID and the message ID in the path. Each attempt carries its outcome, HTTP status code, response body (cut to its first 4096 bytes, with response_truncated set), response time and the URL it was sent to, and whether it was a scheduled attempt or a manual retry. Returns at most 50 attempts, the newest 50; `truncated` is true when the delivery has more. The event payload is never returned.", "tags": [ "Triggers" ], "summary": "List the attempts behind one delivery", "operationId": "TriggerService_ListTriggerDeliveryAttemptsByMessage", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the trigger delivery endpoint the attempts were made to. 1-256 characters.", "name": "endpoint_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Message ID of the delivery, as returned in msg_id by ListTriggerDeliveriesByEndpoint: `msg_` followed by 1 to 64 letters or digits.", "name": "msg_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The delivery's attempts, oldest first, with truncated set when more than 50 exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersListTriggerDeliveryAttemptsByMessageResponse" } } } }, "400": { "description": "Invalid request - endpoint_id is missing, is longer than 256 characters or contains characters other than letters, digits, `.`, `_` and `-`; msg_id is not a message ID (`msg_` followed by 1 to 64 letters or digits); or the endpoint or the message does not exist in this environment", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - Triggers is not enabled for the environment", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - deliveries are being read too often. Retry shortly; the request is not retried on your behalf", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the attempts could not be read; retry the request", "content": { "application/json": { "schema": {} } } } } } }, "/api/v1/trigger-delivery/endpoints/{endpoint_id}:recover": { "post": { "description": "Starts a recovery that resends every trigger event whose delivery to one endpoint failed within a time window. Use this endpoint once your endpoint is healthy again after an outage, instead of resending each failed delivery with BatchResendTriggerDeliveries. Pass the delivery endpoint ID in the path, and `since` and optionally `until` in the body. The recovery covers events with a failed attempt to this endpoint from `since` up to, not including, `until`. It skips an event that also has a successful attempt to this endpoint within the window, and it never sends an event that was not already sent to this endpoint. The window is at most 14 days; omit `until` to recover up to the present. The recovery runs in the background after this call returns, so the response confirms that it started, not that anything was delivered. Each recovered event gets a new attempt, which appears in ListTriggerDeliveriesByEndpoint and ListTriggerDeliveryAttemptsByMessage like any other. One call recovers at most 10,000 events and stops there without reporting it: when more may have failed, cover the period with several calls over narrower windows. Recovery progress cannot be read through the API. `task_id` identifies this recovery in Scalekit's logs for support, and there is no endpoint to poll it. Not idempotent: calling again re-queues every event that is still failed, and a second call made before the first finishes can queue a second attempt for the same event. Returns the recovery's task_id and its status when this call returned. The event payload is never returned.", "tags": [ "Triggers" ], "summary": "Resend failed deliveries to an endpoint", "operationId": "TriggerService_RecoverTriggerDeliveries", "parameters": [ { "schema": { "type": "string" }, "description": "ID of the delivery endpoint whose failed deliveries to resend: `ep_` followed by 1 to 64 letters or digits.", "name": "endpoint_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The recovery started; includes its task_id and its status when this call returned. Events are resent in the background after this response. In the rare case that the recovery was accepted without an identifier, task_id and status are empty; the recovery still runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersRecoverTriggerDeliveriesResponse" } } } }, "400": { "description": "Invalid request, no recovery started - `endpoint_id` is not an endpoint ID (`ep_` followed by 1 to 64 letters or digits); `since` is missing, or `since` or `until` is not a valid timestamp; `since` is in the future; `until` is in the future; `until` is not after `since`; or `until` is more than 14 days after `since`, measured to now when `until` is omitted, so the period must be split into several calls", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - the endpoint is not one of this environment's trigger delivery endpoints, or Triggers is not enabled for the environment. No recovery started", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Too many requests - this environment has started too many recoveries in a short period, or requests are being refused for volume. No recovery started; retry after a short wait", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the recovery was not confirmed. Either it could not be started, or the request timed out or failed after it may already have been accepted, in which case the error message says it may be running. In that case look for new manual attempts with ListTriggerDeliveriesByEndpoint before calling again, because a second call can queue a second attempt for the same event", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerServiceRecoverTriggerDeliveriesBody" } } }, "required": true } } }, "/api/v1/trigger-usage": { "get": { "description": "Returns the trigger deliveries metered for this environment over a period, either a preset period ending now or a range of UTC calendar dates. Use this endpoint to chart trigger usage, for example the last 24 hours by the hour or the current month by the day. Ask for the period in one of two ways, never both: `period`, or `from` and `to`. With `period=24h` the counts are hourly, in `hours`, for the 24 UTC clock hours ending with the hour in progress, which the response names as `current_hour`; that hour's count grows until it ends. With `period=7d` or `period=30d` the counts are daily, in `days`, for the UTC calendar days ending with today's UTC date: the week ending today, or the 30 days ending today. With `from` and `to` the counts are daily, in `days`, for each UTC calendar day from `from` to `to`, both inclusive. Days follow UTC, not the caller's time zone. One unit is one trigger event sent to one receiving endpoint, so an event delivered to several endpoints counts once for each, and a filtered or duplicate event, a failed handoff, or an event no endpoint receives counts none. Only hours and days with metered units are returned: one with none is absent rather than listed as zero, so fill the gaps yourself over the bounds the response returns. Usage is recorded with a short delay, so the latest deliveries can be missing from the current hour's and today's count for a short while. The readable window is today's UTC date and the 30 days before it, and every `period` falls inside it. A `from` and `to` range that extends past the window is clamped to it: a `from` more than 30 days before today's UTC date reads from the first day of the window, and a `to` after today's UTC date reads through today. A range with no day inside the window is refused, as is a `from` after `to`. Returns the range actually read as `from` and `to`, which differ from the request when it was clamped, the `period` asked for, the size of each entry as `bucket`, and the server's UTC date as `today`, so you can tell the day still in progress apart from completed ones.", "tags": [ "Triggers" ], "summary": "Get metered trigger usage", "operationId": "TriggerService_GetTriggerUsage", "parameters": [ { "schema": { "type": "string" }, "description": "First UTC calendar date to include, as YYYY-MM-DD. Inclusive. Required when `period` is not sent, and must be left empty when it is. Must be a real date, must not be after `to`, and must not be after today's UTC date. A date more than 30 days before today's UTC date is clamped to the first day of the readable window, 30 days before today.", "name": "from", "in": "query" }, { "schema": { "type": "string" }, "description": "Last UTC calendar date to include, as YYYY-MM-DD. Inclusive. Required when `period` is not sent, and must be left empty when it is. Must be a real date and must not be more than 30 days before today's UTC date. A date after today's UTC date is clamped to today.", "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ] }, "description": "A preset period ending now, sent instead of `from` and `to`: exactly `24h`, `7d` or `30d`, lowercase. `24h` reads hourly counts for the 24 UTC clock hours ending with the hour in progress. `7d` and `30d` read daily counts for the UTC calendar days ending with today's UTC date: the week ending today, or the 30 days ending today. Leave `from` and `to` empty when this is set; when it is not, both are required.", "name": "period", "in": "query" } ], "responses": { "200": { "description": "The metered usage: one entry per hour (`period=24h`, in `hours`) or per UTC day (every other request, in `days`) with metered units, oldest first, plus the range read and today's UTC date", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/triggersGetTriggerUsageResponse" } } } }, "400": { "description": "Invalid request - `period` is not exactly `24h`, `7d` or `30d`; `period` is sent together with `from` or `to`; `period` is not sent and `from` or `to` is missing; a date is not a real calendar date in YYYY-MM-DD form; `from` is after `to`; `from` is after today's UTC date; or `to` is more than 30 days before today's UTC date. A range that only extends past the readable window is clamped, not refused", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found - trigger usage is not metered for this environment (error_code TRIGGER_USAGE_NOT_METERED), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND)", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Internal error - the usage could not be read; retry the request", "content": { "application/json": { "schema": {} } } }, "503": { "description": "Service unavailable - usage data could not be read right now. No partial figures are returned; retry the request later", "content": { "application/json": { "schema": {} } } } } } } }, "webhooks": { "organization.created": { "post": { "summary": "Organization Created", "description": "Triggered when a new organization is created in Scalekit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_1234567890", "type": "organization.created", "object": "Organization", "occurred_at": "2024-01-15T10:30:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "create_time": "2025-12-09T09:25:02.02Z", "deleted_at": null, "display_name": "AcmeCorp", "external_id": "org_external_123", "id": "org_1234567890", "metadata": null, "region_code": "US", "update_time": "2025-12-09T09:25:02.025330364Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.updated": { "post": { "summary": "Organization Updated", "description": "Triggered when an organization or its settings are updated. data is the organization after the update.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_2345678901", "type": "organization.updated", "object": "Organization", "occurred_at": "2024-01-15T10:35:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "create_time": "2025-12-09T09:25:02.02Z", "deleted_at": null, "display_name": "AcmeCorp", "external_id": "org_external_123", "id": "org_1234567890", "metadata": null, "region_code": "US", "update_time": "2025-12-09T09:25:02.025330364Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.deleted": { "post": { "summary": "Organization Deleted", "description": "Triggered when an organization is deleted. Scalekit first deletes the organization's SSO connections and directories, sending organization.sso_deleted and organization.directory_deleted for each, and then sends this event. data is the deleted organization, with deleted_at set.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_3456789012", "type": "organization.deleted", "object": "Organization", "occurred_at": "2024-01-15T10:40:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "create_time": "2025-12-09T09:25:02.02Z", "deleted_at": "2025-12-09T10:25:45.337417Z", "display_name": "AcmeCorp", "external_id": "org_external_123", "id": "org_1234567890", "metadata": null, "region_code": "US", "update_time": "2025-12-09T09:25:02.025330364Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.domain_created": { "post": { "summary": "Organization Domain Created", "description": "Triggered when a domain is added to an organization (organization domain or allowed email domain). The data payload may include txt_record_secret for DNS verification — treat that value as sensitive and do not log it.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomainCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_4567890123", "type": "organization.domain_created", "occurred_at": "2024-01-15T11:00:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "id": "dom_1234567890", "domain": "acmecorp.com", "domain_type": "ORGANIZATION_DOMAIN", "organization_id": "org_1234567890", "txt_record_key": "scalekit-domain-verification", "txt_record_secret": "", "verification_status": "PENDING", "verification_method": "DNS", "updated_at": "2024-01-15T11:00:00.123456789Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.domain_deleted": { "post": { "summary": "Organization Domain Deleted", "description": "Triggered when a domain is removed from an organization. The payload may still include txt_record_secret from the deleted domain record — treat it as sensitive.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomainDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_4567890456", "type": "organization.domain_deleted", "occurred_at": "2024-01-16T09:30:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "id": "dom_1234567890", "domain": "acmecorp.com", "domain_type": "ORGANIZATION_DOMAIN", "organization_id": "org_1234567890", "txt_record_key": "scalekit-domain-verification", "txt_record_secret": "", "verification_status": "VERIFIED", "verification_method": "DNS", "updated_at": "2024-01-16T09:30:00.123456789Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.domain_dns_verification_success": { "post": { "summary": "Organization Domain DNS Verification Success", "description": "Triggered when DNS TXT record validation confirms ownership of an organization domain. Handle txt_record_secret as sensitive if present.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomainDnsVerificationSuccessEvent" }, "example": { "spec_version": "1", "id": "evt_4567890789", "type": "organization.domain_dns_verification_success", "occurred_at": "2024-01-15T12:15:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "id": "dom_1234567890", "domain": "acmecorp.com", "domain_type": "ORGANIZATION_DOMAIN", "organization_id": "org_1234567890", "txt_record_key": "scalekit-domain-verification", "txt_record_secret": "", "verification_status": "VERIFIED", "verification_method": "DNS", "updated_at": "2024-01-15T12:15:00.123456789Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.domain_dns_verification_failed": { "post": { "summary": "Organization Domain DNS Verification Failed", "description": "Triggered when the DNS verification window expires without a successful TXT record match. Handle txt_record_secret as sensitive if present.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDomainDnsVerificationFailedEvent" }, "example": { "spec_version": "1", "id": "evt_4567891012", "type": "organization.domain_dns_verification_failed", "occurred_at": "2024-01-16T11:00:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_1234567890", "data": { "id": "dom_1234567890", "domain": "acmecorp.com", "domain_type": "ORGANIZATION_DOMAIN", "organization_id": "org_1234567890", "txt_record_key": "scalekit-domain-verification", "txt_record_secret": "", "verification_status": "FAILED", "verification_method": "DNS", "updated_at": "2024-01-16T11:00:00.123456789Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.signup": { "post": { "summary": "User Signup", "description": "Sent when a new user signs up through Scalekit's hosted login and creates an organization. A user.organization_membership_created event for the same membership is sent with it. Not sent when an existing user creates another organization or joins one through JIT provisioning.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSignupEvent" }, "example": { "spec_version": "1", "id": "evt_146592100261836544", "type": "user.signup", "occurred_at": "2026-10-08T07:02:11.452710239Z", "environment_id": "env_97917421217645333", "object": "OrgMembershipEvent", "data": { "organization": { "id": "org_146592100188409609", "create_time": "2026-10-08T07:02:11.35Z", "update_time": "2026-10-08T07:02:11.386974Z", "display_name": "", "external_id": null, "region_code": "US", "metadata": null, "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] }, "deleted_at": null }, "user": { "id": "usr_146592100205121289", "email": "ivy.chen@acmecorp.com", "create_time": "2026-10-08T07:02:11.39Z", "update_time": "2026-10-08T07:02:11.391988Z", "last_login_time": null, "metadata": {}, "user_profile": { "id": "usp_146592100205186825", "name": "Ivy Chen", "given_name": "Ivy", "family_name": "Chen", "preferred_username": "", "email_verified": true, "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_type": "OAUTH", "connection_provider": "GOOGLE", "connection_user_id": "105055379523565727691", "is_social": true, "created_time": "2026-10-08T07:02:11.47Z", "last_login_time": "2026-10-08T07:02:11.469311Z", "last_synced_time": "2026-10-08T07:02:11.469311Z" } ] } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.login": { "post": { "summary": "User Login", "description": "Sent each time a user completes login through Scalekit's hosted login, including the first login after signup. data.user_session.organization_id is the organization the user logged in to.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserLoginEvent" }, "example": { "spec_version": "1", "id": "evt_146592100859432713", "type": "user.login", "occurred_at": "2026-10-08T07:02:11.781873312Z", "environment_id": "env_97917421217645333", "object": "UserLoginEvent", "data": { "user": { "id": "usr_146592100205121289", "email": "ivy.chen@acmecorp.com", "create_time": "2026-10-08T07:02:11.39Z", "update_time": "2026-10-08T07:02:11.391988Z", "last_login_time": "2026-10-08T07:02:11.48Z", "metadata": {}, "user_profile": { "id": "usp_146592100205186825", "name": "Ivy Chen", "given_name": "Ivy", "family_name": "Chen", "preferred_username": "", "email_verified": true, "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_type": "OAUTH", "connection_provider": "GOOGLE", "connection_user_id": "105055379523565727691", "is_social": true, "created_time": "2026-10-08T07:02:11.47Z", "last_login_time": "2026-10-08T07:02:11.469311Z", "last_synced_time": "2026-10-08T07:02:11.469311Z" } ] } }, "user_session": { "session_id": "ses_146592100356116233", "user_id": "usr_146592100205121289", "organization_id": "org_146592100188409609", "authenticated_organizations": [ "org_146592100188409609" ], "status": "ACTIVE", "created_at": "2026-10-08T07:02:11.48Z", "updated_at": "2026-10-08T07:02:11.748512Z", "last_active_at": "2026-10-08T07:02:11.747206Z", "absolute_expires_at": "2026-11-07T07:02:11.737394Z", "idle_expires_at": "2026-10-15T07:02:11.737395Z", "expired_at": null, "logout_at": null, "device": { "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36", "os": "macOS", "os_version": "10.15.7", "browser": "Chrome", "browser_version": "142.0.0.0", "device_type": "Desktop", "ip": "203.0.113.24", "location": { "region": "US", "region_subdivision": "USCA", "city": "San Francisco", "latitude": "37.7749", "longitude": "-122.4194" } } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.logout": { "post": { "summary": "User Logout", "description": "Sent when a user's session ends: the user logs out, the identity provider logs the user out, or an active session expires. data.user_session.status is LOGOUT or EXPIRED.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserLogoutEvent" }, "example": { "spec_version": "1", "id": "evt_146600211859477201", "type": "user.logout", "occurred_at": "2026-10-08T09:15:40.130551208Z", "environment_id": "env_97917421217645333", "object": "UserLogoutEvent", "data": { "user": { "id": "usr_146592100205121289", "email": "ivy.chen@acmecorp.com", "create_time": "2026-10-08T07:02:11.39Z", "update_time": "2026-10-08T07:02:11.391988Z", "last_login_time": "2026-10-08T07:02:11.48Z", "metadata": {}, "user_profile": { "id": "usp_146592100205186825", "name": "Ivy Chen", "given_name": "Ivy", "family_name": "Chen", "preferred_username": "", "email_verified": true, "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_type": "OAUTH", "connection_provider": "GOOGLE", "connection_user_id": "105055379523565727691", "is_social": true, "created_time": "2026-10-08T07:02:11.47Z", "last_login_time": "2026-10-08T07:02:11.469311Z", "last_synced_time": "2026-10-08T07:02:11.469311Z" } ] } }, "user_session": { "session_id": "ses_146592100356116233", "user_id": "usr_146592100205121289", "organization_id": "org_146592100188409609", "authenticated_organizations": [ "org_146592100188409609" ], "status": "LOGOUT", "created_at": "2026-10-08T07:02:11.48Z", "updated_at": "2026-10-08T09:15:40.112003Z", "last_active_at": "2026-10-08T09:15:40.101772Z", "absolute_expires_at": "2026-11-07T07:02:11.737394Z", "idle_expires_at": null, "expired_at": null, "logout_at": "2026-10-08T09:15:40.111978Z", "device": { "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36", "os": "macOS", "os_version": "10.15.7", "browser": "Chrome", "browser_version": "142.0.0.0", "device_type": "Desktop", "ip": "203.0.113.24", "location": { "region": "US", "region_subdivision": "USCA", "city": "San Francisco", "latitude": "37.7749", "longitude": "-122.4194" } } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_invitation": { "post": { "summary": "User Organization Invitation", "description": "Sent when you create a user in an organization and Scalekit sends them an invitation email (send_invitation_email is true, the default). When the user accepts, user.organization_membership_created follows.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOrganizationInvitationEvent" }, "example": { "spec_version": "1", "id": "evt_146588054637773430", "type": "user.organization_invitation", "occurred_at": "2026-10-08T06:21:29.256055794Z", "environment_id": "env_97917421217645333", "object": "OrgMembershipEvent", "data": { "organization": { "id": "org_146588053631140796", "create_time": "2026-10-08T06:21:28.65Z", "update_time": "2026-10-08T06:21:28.654334Z", "display_name": "Acme Corp", "external_id": null, "region_code": "US", "metadata": null, "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] }, "deleted_at": null }, "user": { "id": "usr_146588054151234166", "email": "ivy.chen@acmecorp.com", "create_time": "2026-10-08T06:21:28.96Z", "update_time": "2026-10-08T06:21:28.960277Z", "last_login_time": null, "metadata": { "plan": "pro" }, "user_profile": { "id": "usp_146588054151299702", "name": "", "given_name": "Ivy", "family_name": "Chen", "preferred_username": "", "email_verified": false, "phone_number": "", "phone_number_verified": false, "picture": "", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": null }, "external_id": "ext_8812" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_membership_created": { "post": { "summary": "User Organization Membership Created", "description": "Sent when a user becomes an active member of an organization: you create the user without an invitation, the user accepts an invitation, signs up, or joins through JIT or SCIM provisioning.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOrganizationMembershipCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_146588058974683830", "type": "user.organization_membership_created", "occurred_at": "2026-10-08T06:21:31.731842067Z", "environment_id": "env_97917421217645333", "object": "OrgMembershipEvent", "data": { "organization": { "id": "org_146588053631140796", "create_time": "2026-10-08T06:21:28.65Z", "update_time": "2026-10-08T06:21:28.654334Z", "display_name": "Acme Corp", "external_id": null, "region_code": "US", "metadata": null, "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] }, "deleted_at": null }, "user": { "id": "usr_146588058748191350", "email": "max.patel@acmecorp.com", "create_time": "2026-10-08T06:21:31.7Z", "update_time": "2026-10-08T06:21:31.700660Z", "last_login_time": null, "metadata": {}, "user_profile": { "id": "usp_146588058748256886", "name": "", "given_name": "Max", "family_name": "Patel", "preferred_username": "", "email_verified": false, "phone_number": "", "phone_number_verified": false, "picture": "", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": null } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_membership_deleted": { "post": { "summary": "User Organization Membership Deleted", "description": "Sent when a user leaves an organization: the membership or the user is deleted, the organization is deleted, or the directory provider deactivates or deletes the user.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOrganizationMembershipDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_146588067415339158", "type": "user.organization_membership_deleted", "occurred_at": "2026-10-08T06:21:36.427016554Z", "environment_id": "env_97917421217645333", "object": "OrgMembershipEvent", "data": { "organization": { "id": "org_146588053631140796", "create_time": "2026-10-08T06:21:28.65Z", "update_time": "2026-10-08T06:21:28.654334Z", "display_name": "Acme Corp", "external_id": null, "region_code": "US", "metadata": null, "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] }, "deleted_at": null }, "user": { "id": "usr_146588058748191350", "email": "max.patel@acmecorp.com", "create_time": "2026-10-08T06:21:31.7Z", "update_time": "2026-10-08T06:21:31.700660Z", "last_login_time": null, "metadata": {}, "user_profile": { "id": "usp_146588058748256886", "name": "", "given_name": "Max", "family_name": "Patel", "preferred_username": "", "email_verified": false, "phone_number": "", "phone_number_verified": false, "picture": "", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": null } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_membership_updated": { "post": { "summary": "User Organization Membership Updated", "description": "Sent when a membership is updated through the API, and on each SCIM update of a provisioned member, even when the update changes nothing. data is the user and organization after the update.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserOrganizationMembershipUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_146588063102937238", "type": "user.organization_membership_updated", "occurred_at": "2026-10-08T06:21:34.165394170Z", "environment_id": "env_97917421217645333", "object": "OrgMembershipEvent", "data": { "organization": { "id": "org_146588053631140796", "create_time": "2026-10-08T06:21:28.65Z", "update_time": "2026-10-08T06:21:28.654334Z", "display_name": "Acme Corp", "external_id": null, "region_code": "US", "metadata": null, "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] }, "deleted_at": null }, "user": { "id": "usr_146588058748191350", "email": "max.patel@acmecorp.com", "create_time": "2026-10-08T06:21:31.7Z", "update_time": "2026-10-08T06:21:31.700660Z", "last_login_time": null, "metadata": {}, "user_profile": { "id": "usp_146588058748256886", "name": "", "given_name": "Max", "family_name": "Patel", "preferred_username": "", "email_verified": false, "phone_number": "", "phone_number_verified": false, "picture": "", "gender": "", "locale": "", "metadata": {}, "custom_attributes": null, "groups": null, "external_identities": null } } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory_created": { "post": { "summary": "Directory Created", "description": "Triggered when a directory is created for an organization. A SCIM or LDAP directory is enabled on creation, so organization.directory_enabled follows. A POLL directory is created disabled and sends only this event.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDirectoryCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_55136848686612000", "type": "organization.directory_created", "object": "Directory", "occurred_at": "2025-01-15T08:55:22.702860294Z", "environment_id": "env_27758032200925221", "organization_id": "org_55135410258444802", "data": { "directory_type": "SCIM", "id": "dir_55135622825771522", "organization_id": "org_55135410258444802", "provider": "OKTA" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory_enabled": { "post": { "summary": "Directory Enabled", "description": "Triggered when a directory sync is enabled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDirectoryEnabledEvent" }, "example": { "spec_version": "1", "id": "evt_55136848686613000", "type": "organization.directory_enabled", "object": "Directory", "occurred_at": "2025-01-15T08:55:22.802860294Z", "environment_id": "env_27758032200925221", "organization_id": "org_55135410258444802", "data": { "directory_type": "SCIM", "enabled": true, "id": "dir_55135622825771522", "organization_id": "org_55135410258444802", "provider": "OKTA", "updated_at": "2025-01-15T08:55:22.792993454Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory_disabled": { "post": { "summary": "Directory Disabled", "description": "Triggered when a directory sync is disabled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDirectoryDisabledEvent" }, "example": { "spec_version": "1", "id": "evt_53891640779079756", "type": "organization.directory_disabled", "object": "Directory", "occurred_at": "2025-01-06T18:45:21.057814Z", "environment_id": "env_53814739859406915", "organization_id": "org_53879494091473415", "data": { "directory_type": "SCIM", "id": "dir_53879621145330183", "organization_id": "org_53879494091473415", "provider": "OKTA" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory_deleted": { "post": { "summary": "Directory Deleted", "description": "Triggered when a directory is deleted. Deleting a directory through the API or dashboard requires disabling it first. Deleting an organization also deletes its directories, enabled or not, and sends this event for each.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDirectoryDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_53891640779079900", "type": "organization.directory_deleted", "object": "Directory", "occurred_at": "2025-01-06T18:50:02.118243Z", "environment_id": "env_53814739859406915", "organization_id": "org_53879494091473415", "data": { "directory_type": "SCIM", "id": "dir_53879621145330183", "organization_id": "org_53879494091473415", "provider": "OKTA" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.user_created": { "post": { "summary": "Directory User Created", "description": "Triggered when the directory provider creates an active user, or reactivates a deactivated user", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryUserCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_53891546994442316", "type": "organization.directory.user_created", "object": "DirectoryUser", "occurred_at": "2025-01-06T18:44:25.153954Z", "environment_id": "env_53814739859406915", "organization_id": "org_53879494091473415", "data": { "active": true, "custom_attributes": { "mobile_phone_number": "+1-555-0101" }, "department": "Engineering", "dp_id": "00u1a2b3c4d5e6f7g8h9", "email": "john.doe@acmecorp.com", "employee_id": "E1234", "family_name": "Doe", "given_name": "John", "groups": [ { "id": "dirgroup_53891546960887900", "name": "Engineering" } ], "id": "diruser_53891546960887884", "locale": "en-US", "name": "John Doe", "organization_id": "org_53879494091473415", "phone_number": "+1-555-0100", "preferred_username": "john.doe@acmecorp.com", "raw_attributes": { "active": true, "externalId": "00u1a2b3c4d5e6f7g8h9", "userName": "john.doe@acmecorp.com" }, "roles": [ { "role_name": "billing_admin" } ], "title": "Software Engineer", "zoneinfo": "America/New_York" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.user_updated": { "post": { "summary": "Directory User Updated", "description": "Triggered when an active user's attributes change, or when the user is added to or removed from a group", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryUserUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_53891546994442317", "type": "organization.directory.user_updated", "object": "DirectoryUser", "occurred_at": "2025-01-06T18:44:25.153954Z", "environment_id": "env_53814739859406915", "organization_id": "org_53879494091473415", "data": { "active": true, "custom_attributes": { "mobile_phone_number": "+1-555-0101" }, "department": "Engineering", "dp_id": "00u1a2b3c4d5e6f7g8h9", "email": "john.doe@acmecorp.com", "employee_id": "E1234", "family_name": "Doe", "given_name": "John", "groups": [ { "id": "dirgroup_53891546960887900", "name": "Engineering" } ], "id": "diruser_53891546960887884", "locale": "en-US", "name": "John Doe", "organization_id": "org_53879494091473415", "phone_number": "+1-555-0100", "preferred_username": "john.doe@acmecorp.com", "raw_attributes": { "active": true, "externalId": "00u1a2b3c4d5e6f7g8h9", "userName": "john.doe@acmecorp.com" }, "roles": [ { "role_name": "billing_admin" } ], "title": "Senior Software Engineer", "zoneinfo": "America/New_York" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.user_deleted": { "post": { "summary": "Directory User Deleted", "description": "Triggered when an active user is deactivated or deleted in the directory provider. The data object carries the last known user record; active is false when the user was deactivated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryUserDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_53891546994442318", "type": "organization.directory.user_deleted", "object": "DirectoryUser", "occurred_at": "2025-01-06T18:44:25.153954Z", "environment_id": "env_53814739859406915", "organization_id": "org_53879494091473415", "data": { "active": false, "custom_attributes": { "mobile_phone_number": "+1-555-0101" }, "department": "Engineering", "dp_id": "00u1a2b3c4d5e6f7g8h9", "email": "john.doe@acmecorp.com", "employee_id": "E1234", "family_name": "Doe", "given_name": "John", "groups": [ { "id": "dirgroup_53891546960887900", "name": "Engineering" } ], "id": "diruser_53891546960887884", "locale": "en-US", "name": "John Doe", "organization_id": "org_53879494091473415", "phone_number": "+1-555-0100", "preferred_username": "john.doe@acmecorp.com", "raw_attributes": { "active": false, "externalId": "00u1a2b3c4d5e6f7g8h9", "userName": "john.doe@acmecorp.com" }, "roles": [ { "role_name": "billing_admin" } ], "title": "Software Engineer", "zoneinfo": "America/New_York" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.group_created": { "post": { "summary": "Directory Group Created", "description": "Triggered when a new directory group is created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryGroupCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_38862741515010639", "type": "organization.directory.group_created", "object": "DirectoryGroup", "occurred_at": "2024-09-25T02:26:39.036398577Z", "environment_id": "env_32080745237316098", "organization_id": "org_38609339635728478", "data": { "directory_id": "dir_38610496391217780", "display_name": "Engineering", "dp_id": "00g1a2b3c4d5e6f7g8h9", "id": "dirgroup_38862741498233423", "organization_id": "org_38609339635728478", "raw_attributes": { "displayName": "Engineering", "externalId": "00g1a2b3c4d5e6f7g8h9" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.group_updated": { "post": { "summary": "Directory Group Updated", "description": "Triggered when a directory group is updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryGroupUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_38864948910162368", "type": "organization.directory.group_updated", "object": "DirectoryGroup", "occurred_at": "2024-09-25T02:48:34.745030921Z", "environment_id": "env_32080745237316098", "organization_id": "org_38609339635728478", "data": { "directory_id": "dir_38610496391217780", "display_name": "Platform Engineering", "dp_id": "00g1a2b3c4d5e6f7g8h9", "id": "dirgroup_38862741498233423", "organization_id": "org_38609339635728478", "raw_attributes": { "displayName": "Platform Engineering", "externalId": "00g1a2b3c4d5e6f7g8h9" } } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.group_deleted": { "post": { "summary": "Directory Group Deleted", "description": "Triggered when a directory group is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryGroupDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_40650399597723966", "type": "organization.directory.group_deleted", "object": "DirectoryGroup", "occurred_at": "2024-10-07T10:25:26.289331747Z", "environment_id": "env_12205603854221623", "organization_id": "org_39802449573184223", "data": { "directory_id": "dir_39802485862301855", "display_name": "Admins", "dp_id": "7c66a173-79c6-4270-ac78-8f35a8121e0a", "id": "dirgroup_40072007005503806", "organization_id": "org_39802449573184223", "raw_attributes": {} } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.sso_created": { "post": { "summary": "SSO Connection Created", "description": "Triggered when a new SSO connection is created for an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSsoCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_94567862441607493", "type": "organization.sso_created", "object": "Connection", "environment_id": "env_74418471961625391", "occurred_at": "2025-10-14T09:27:18.488720586Z", "organization_id": "org_83544995172188677", "data": { "connection_type": "OIDC", "enabled": false, "id": "conn_94567862424830277", "organization_id": "org_83544995172188677", "provider": "OKTA", "status": "DRAFT" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.sso_enabled": { "post": { "summary": "SSO Connection Enabled", "description": "Triggered when an SSO connection is enabled for an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSsoEnabledEvent" }, "example": { "spec_version": "1", "id": "evt_94568078213382471", "type": "organization.sso_enabled", "object": "Connection", "environment_id": "env_74418471961625391", "occurred_at": "2025-10-14T09:29:27.098914861Z", "organization_id": "org_83544995172188677", "data": { "connection_type": "OIDC", "enabled": true, "id": "conn_94567862424830277", "organization_id": "org_83544995172188677", "provider": "OKTA", "status": "COMPLETED" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.sso_disabled": { "post": { "summary": "SSO Connection Disabled", "description": "Triggered when an SSO connection is disabled for an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSsoDisabledEvent" }, "example": { "spec_version": "1", "id": "evt_94557976165089560", "type": "organization.sso_disabled", "object": "Connection", "environment_id": "env_74418471961625391", "occurred_at": "2025-10-14T07:49:05.809554456Z", "organization_id": "org_83544995172188677", "data": { "connection_type": "OIDC", "enabled": false, "id": "conn_83545002856153607", "organization_id": "org_83544995172188677", "provider": "OKTA", "status": "COMPLETED" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.sso_deleted": { "post": { "summary": "SSO Connection Deleted", "description": "Triggered when an SSO connection is deleted for an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSsoDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_94557997639926040", "type": "organization.sso_deleted", "object": "Connection", "environment_id": "env_74418471961625391", "occurred_at": "2025-10-14T07:49:18.604546332Z", "organization_id": "org_83544995172188677", "data": { "connection_type": "OIDC", "enabled": false, "id": "conn_83545002856153607", "organization_id": "org_83544995172188677", "provider": "OKTA", "status": "COMPLETED" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "role.created": { "post": { "summary": "Role Created", "description": "Triggered when a new role is created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_1234567890", "type": "role.created", "object": "Role", "occurred_at": "2024-01-15T10:30:00.123456789Z", "environment_id": "env_1234567890", "data": { "description": "Viewer role with read-only access", "display_name": "Viewer", "extends": "member", "id": "role_1234567890", "name": "viewer" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "role.updated": { "post": { "summary": "Role Updated", "description": "Triggered when a role is updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_2345678901", "type": "role.updated", "object": "Role", "occurred_at": "2024-01-15T10:35:00.123456789Z", "environment_id": "env_1234567890", "data": { "description": "Updated viewer role with limited permissions", "display_name": "Viewer", "extends": "member", "id": "role_1234567890", "name": "viewer" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "role.deleted": { "post": { "summary": "Role Deleted", "description": "Triggered when a role is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_3456789012", "type": "role.deleted", "object": "Role", "occurred_at": "2024-01-15T10:40:00.123456789Z", "environment_id": "env_1234567890", "data": { "description": "Updated viewer role with limited permissions", "display_name": "Viewer", "extends": "member", "id": "role_1234567890", "name": "viewer" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "permission.created": { "post": { "summary": "Permission Created", "description": "Triggered when a new permission is created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionCreatedEvent" }, "example": { "spec_version": "1", "id": "evt_1234567890", "type": "permission.created", "object": "Permission", "occurred_at": "2024-01-15T10:30:00.123456789Z", "environment_id": "env_1234567890", "data": { "description": "Permission to manage data", "id": "perm_1234567890", "name": "data:manage" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "permission.updated": { "post": { "summary": "Permission Updated", "description": "Triggered when a permission is updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionUpdatedEvent" }, "example": { "spec_version": "1", "id": "evt_2345678901", "type": "permission.updated", "object": "Permission", "occurred_at": "2024-01-15T10:35:00.123456789Z", "environment_id": "env_1234567890", "data": { "description": "Updated permission to manage all data", "id": "perm_1234567890", "name": "data:manage" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "permission.deleted": { "post": { "summary": "Permission Deleted", "description": "Triggered when a permission is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionDeletedEvent" }, "example": { "spec_version": "1", "id": "evt_3456789012", "type": "permission.deleted", "object": "Permission", "occurred_at": "2024-01-15T10:40:00.123456789Z", "environment_id": "env_1234567890", "data": { "description": "Updated permission to manage all data", "id": "perm_1234567890", "name": "data:manage" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "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", "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", "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" }, "display_name": "OAuth tokens fetched" } } } }, "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" }, "display_name": "OAuth authentication successful" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } }, "components": { "schemas": { "auditlogsListAuthLogResponse": { "type": "object", "properties": { "authRequests": { "description": "Authentication requests matching the filter, ordered most-recent first. Empty when no events match.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/auditlogsAuthLogRequest" } }, "next_page_token": { "description": "Opaque cursor for the next page. Empty when the current page is the last. Pass back as page_token to fetch the next page.", "type": "string", "examples": [ "3" ] }, "prev_page_token": { "description": "Opaque cursor for the previous page. Empty when the current page is the first. Pass back as page_token to fetch the previous page.", "type": "string", "examples": [ "1" ] }, "total_size": { "description": "Total number of authentication requests matching the filter across all pages.", "type": "integer", "format": "int64", "examples": [ 128 ] } } }, "auditlogsAuthLogRequest": { "type": "object", "properties": { "auth_request_id": { "description": "Unique identifier for this authentication request.", "type": "string", "examples": [ "ar_1234567890123456" ] }, "client_id": { "description": "Unique identifier of the client associated with this authentication event", "type": "string", "examples": [ "skc_1234567890" ] }, "client_name": { "description": "Display name of the client", "type": "string", "examples": [ "Default" ] }, "client_type": { "description": "Type of the client application (e.g., ENV, NTV, SPA, M2M)", "type": "string", "examples": [ "ENV" ] }, "connection_details": { "description": "Connections involved in this authentication request, including provider and organization context.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/auditlogsConnectionDetails" } }, "connection_id": { "description": "Primary connection ID used for this authentication request.", "type": "string", "examples": [ "conn_1234567890123456" ] }, "connection_provider": { "description": "Identity provider for the primary connection (for example OKTA or GOOGLE).", "type": "string", "examples": [ "OKTA" ] }, "connection_type": { "description": "Type of the primary connection (for example OIDC or SAML).", "type": "string", "examples": [ "OIDC" ] }, "email": { "description": "End-user email associated with the authentication attempt, when available.", "type": "string", "examples": [ "user@example.com" ] }, "environment_id": { "description": "Environment ID where the authentication request occurred.", "type": "string", "examples": [ "env_1234567890123456" ] }, "organization_id": { "description": "Organization ID associated with this authentication request, when resolved.", "type": "string", "examples": [ "org_1234567890123456" ] }, "resource_id": { "description": "Resource identifier associated with this authentication request, when present.", "type": "string", "examples": [ "res_1234567890" ] }, "resource_name": { "description": "Display name of the resource associated with this authentication request, when present.", "type": "string", "examples": [ "Production MCP Server" ] }, "resource_type": { "description": "Type of the resource associated with this authentication request, when present.", "type": "string", "examples": [ "mcp" ] }, "status": { "description": "Outcome of the authentication request: INITIATED, PENDING, SUCCESS, or FAILED.", "type": "string", "enum": [ "INITIATED", "PENDING", "SUCCESS", "FAILED" ], "examples": [ "SUCCESS" ] }, "timestamp": { "description": "UTC timestamp when this authentication request was recorded.", "type": "string", "format": "date-time", "examples": [ "2024-06-15T14:30:00Z" ] }, "workflow": { "description": "Authentication workflow that produced this log entry, when available.", "type": "string", "examples": [ "sso" ] } } }, "auditlogsConnectionDetails": { "type": "object", "properties": { "connection_id": { "description": "Connection ID for this connection detail entry.", "type": "string", "examples": [ "conn_1234567890123456" ] }, "connection_provider": { "description": "Identity provider for this connection.", "type": "string", "examples": [ "OKTA" ] }, "connection_type": { "description": "Connection type (for example OIDC or SAML).", "type": "string", "examples": [ "OIDC" ] }, "organization_id": { "description": "Organization that owns this connection.", "type": "string", "examples": [ "org_1234567890123456" ] } } }, "HelpInfoLink": { "description": "A documentation or reference link.", "type": "object", "properties": { "description": { "description": "Human-readable label for the link (e.g. \"User verification flow\").", "type": "string" }, "url": { "description": "Absolute URL to the documentation page (e.g. \"https://docs.scalekit.com/...\").", "type": "string" } } }, "McpServiceCreateMcpSessionTokenBody": { "type": "object", "required": [ "identifier" ], "properties": { "access_level": { "description": "Which tools the token can use. `READ_ONLY` limits it to the server's read-only tools; other tools are left out of `tools/list` and refused when called. `FULL`, or omitting the field, gives every tool the server serves. Case-sensitive.", "type": "string", "enum": [ "FULL", "READ_ONLY" ], "examples": [ "READ_ONLY" ] }, "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": { "access_level": { "description": "Which tools the token can use. `READ_ONLY` limits it to the server's read-only tools; other tools are left out of `tools/list` and refused when called. `FULL`, or omitting the field, gives every tool the server serves. Case-sensitive.", "type": "string", "enum": [ "FULL", "READ_ONLY" ], "examples": [ "READ_ONLY" ] }, "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 connections in `DIRECT` mode.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/mcpMcpConfigConnectionToolMapping" } }, "tool_exposure": { "description": "Change how the server exposes tools to agents: `DIRECT` or `META`. Leave it out to keep the current mode. Switching to `DIRECT` fails when the server has more than 25 connections. After a switch, MCP clients must list the tools again; session tokens keep working.", "$ref": "#/components/schemas/mcpToolExposure", "examples": [ "META" ] }, "description": { "description": "Updated description for the MCP configuration", "type": "string", "examples": [ "Updated daily summarizer config" ] } } }, "OrganizationServiceUpdateOrganizationSessionPolicyBody": { "type": "object", "properties": { "absolute_session_timeout": { "description": "The absolute session timeout value. The unit is specified by absolute_session_timeout_unit. Omit when policy_source is APPLICATION.", "type": "integer", "format": "int32", "examples": [ 360 ] }, "absolute_session_timeout_unit": { "description": "Unit for absolute_session_timeout. Accepted values: 'MINUTES', 'HOURS', 'DAYS'. Defaults to MINUTES.", "$ref": "#/components/schemas/commonsTimeUnit", "examples": [ "MINUTES" ] }, "idle_session_timeout": { "description": "The idle session timeout value. The unit is specified by idle_session_timeout_unit. Omit when idle_session_timeout_enabled is false.", "type": "integer", "format": "int32", "examples": [ 84 ] }, "idle_session_timeout_enabled": { "description": "Whether idle session timeout is enabled. Omit when policy_source is APPLICATION.", "type": "boolean", "examples": [ true ] }, "idle_session_timeout_unit": { "description": "Unit for idle_session_timeout. Accepted values: 'MINUTES', 'HOURS', 'DAYS'. Defaults to MINUTES.", "$ref": "#/components/schemas/commonsTimeUnit", "examples": [ "MINUTES" ] }, "policy_source": { "description": "Policy source. Send 'APPLICATION' to revert to application defaults. Send 'CUSTOM' with timeout values to activate a custom policy.", "$ref": "#/components/schemas/organizationsSessionPolicyType", "examples": [ "CUSTOM" ] } } }, "OrganizationServiceUpsertUserManagementSettingsBody": { "type": "object", "properties": { "settings": { "description": "The new values for the setting fields to patch.", "$ref": "#/components/schemas/organizationsOrganizationUserManagementSettings" } } }, "RolesServiceAddPermissionsToRoleBody": { "type": "object", "properties": { "permission_names": { "description": "List of permission names to add to the role", "type": "array", "items": { "type": "string" } } } }, "RolesServiceUpdateDefaultOrganizationRolesBody": { "type": "object", "properties": { "default_member_role": { "description": "Unique name of the default member role", "type": "string", "examples": [ "member" ] } } }, "UserServiceResendInviteBody": { "type": "object" }, "ValidationErrorInfoFieldViolation": { "description": "A message type used to describe a single bad request field.", "type": "object", "properties": { "constraint": { "type": "string" }, "description": { "description": "A description of why the request element is bad.", "type": "string" }, "field": { "type": "string" } } }, "WebAuthConfigurationAttestation": { "type": "object", "title": "Attestation preferences for registration", "properties": { "conveyance_preference": { "type": "string", "title": "Conveyance preference" }, "enterprise_approved_ids": { "type": "array", "title": "Enterprise-approved IDs (optional allowlist when enterprise attestation is used)", "items": { "type": "string" } } } }, "WebAuthConfigurationAuthenticatorSelection": { "type": "object", "properties": { "authenticator_attachment": { "type": "string" }, "user_verification": { "type": "string", "title": "User verification requirement" } } }, "WebAuthConfigurationAuthenticators": { "type": "object", "properties": { "desired_authenticator_status": { "description": "provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate_status set to true.", "type": "array", "items": { "type": "string", "default": "[]" } }, "undesired_authenticator_status": { "description": "provides the list of statuses which are considered undesirable for status report validation purposes. Should be used with validate_status set to true.", "type": "array", "items": { "type": "string", "default": "['ATTESTATION_KEY_COMPROMISE', 'USER_VERIFICATION_BYPASS', 'USER_KEY_REMOTE_COMPROMISE', 'USER_KEY_PHYSICAL_COMPROMISE', 'REVOKED']" } }, "validate_anchors": { "description": "when set to true enables the validation of the attestation statement against the trust anchor from the metadata statement.", "type": "boolean" }, "validate_attestation_type": { "description": "when set to true enables the validation of the attestation statements type against the known types the authenticator can produce.", "type": "boolean" }, "validate_entry": { "description": "requires that the provided metadata has an entry for the given authenticator to be considered valid. By default an AAGUID which has a zero value should fail validation if validate_entry_permit_zero_aaguid is not provided with the value of true.", "type": "boolean" }, "validate_entry_permit_zero_aaguid": { "description": "is an option that permits a zero'd AAGUID from an attestation statement to automatically pass metadata validations. Generally helpful to use with validate_entry.", "type": "boolean" }, "validate_status": { "description": "when set to true enables the validation of the attestation statements AAGUID against the desired and undesired lists", "type": "boolean" } } }, "WebAuthConfigurationRp": { "type": "object", "title": "Rp contains relying party identifiers and origins", "properties": { "ids": { "type": "array", "title": "Relying party IDs (derived from environment domain and verified custom domain)\nAt least one required; must be hostnames without scheme or path", "items": { "type": "string" } }, "origins": { "type": "array", "title": "Allowed origins corresponding to the RP IDs (https://)\nAt least one required; must be HTTPS origins", "items": { "type": "string" } } } }, "WebAuthConfigurationTimeout": { "type": "object", "properties": { "login": { "description": "Login timeout duration", "type": "string", "default": "\"300s\"" }, "login_uvd": { "description": "Login timeout duration when user verification is discouraged", "type": "string", "default": "\"300s\"" }, "registration": { "description": "Registration timeout duration", "type": "string", "default": "\"300s\"" }, "registration_uvd": { "description": "Registration timeout duration when user verification is discouraged", "type": "string", "default": "\"300s\"" } } }, "WebAuthnCredentialAuthenticator": { "type": "object", "properties": { "aaguid": { "description": "Authenticator Attestation GUID (AAGUID) identifying the device model", "type": "string" }, "attachment": { "description": "Attachment type: \"platform\" (built-in) or \"cross-platform\"", "type": "string", "examples": [ "platform" ] }, "icon_dark": { "description": "Icon URL for dark theme display", "type": "string" }, "icon_light": { "description": "Icon URL for light theme display", "type": "string" }, "name": { "description": "Human-readable name of the authenticator model", "type": "string", "examples": [ "Apple Touch ID" ] } } }, "WebAuthnCredentialAuthenticatorFlags": { "type": "object", "properties": { "backup_eligible": { "description": "Whether this credential can be backed up to another device", "type": "boolean" }, "backup_state": { "description": "Whether this credential was synced or backed up", "type": "boolean" }, "user_present": { "description": "Whether the user was present during authentication", "type": "boolean" }, "user_verified": { "description": "Whether the user was verified (e.g., fingerprint, PIN)", "type": "boolean" } } }, "WebAuthnCredentialClientInfo": { "type": "object", "properties": { "city": { "description": "City name", "type": "string", "examples": [ "San Francisco" ] }, "ip": { "description": "IP address from which credential was registered", "type": "string", "examples": [ "192.0.2.1" ] }, "region": { "description": "Geographic region (e.g., \"US\")", "type": "string", "examples": [ "US" ] }, "region_subdivision": { "description": "Regional subdivision (e.g., \"CA\")", "type": "string", "examples": [ "CA" ] } } }, "WebAuthnCredentialUserAgent": { "type": "object", "properties": { "browser": { "description": "Browser name (e.g., \"Chrome\", \"Safari\")", "type": "string", "examples": [ "Chrome" ] }, "browser_version": { "description": "Browser version number", "type": "string", "examples": [ "120.0.6099.129" ] }, "device_model": { "description": "Device model if available", "type": "string", "examples": [ "iPhone15,2" ] }, "device_type": { "description": "Device type: \"desktop\", \"mobile\", or \"tablet\"", "type": "string", "examples": [ "mobile" ] }, "os": { "description": "Operating system name (e.g., \"Windows\", \"iOS\")", "type": "string", "examples": [ "macOS" ] }, "os_version": { "description": "Operating system version", "type": "string", "examples": [ "14.2" ] }, "raw": { "description": "Raw user agent string from the browser", "type": "string" }, "url": { "description": "Parsed user agent URL reference", "type": "string" } } }, "WebAuthnServiceUpdateCredentialBody": { "type": "object", "properties": { "display_name": { "description": "Human-friendly name for this credential (1-120 characters)", "type": "string", "examples": [ "My iPhone 15 Pro" ] } } }, "authpasswordlessPasswordlessType": { "type": "string", "enum": [ "OTP", "LINK", "LINK_OTP" ] }, "clientsClientSecret": { "description": "A secure credential used for authenticating an API client. Each client can have multiple secrets for key rotation purposes.", "type": "object", "title": "Client Secret", "properties": { "create_time": { "description": "The timestamp when this secret was created. This field is automatically set by the server and cannot be modified.", "type": "string", "format": "date-time", "examples": [ "2024-01-05T14:48:00Z" ] }, "created_by": { "description": "The identifier of the user or system that created this secret. This field helps track who created the secret for audit and compliance purposes.", "type": "string", "examples": [ "user_12345" ] }, "expire_time": { "description": "The timestamp when this secret will expire. After this time, the secret cannot be used for authentication regardless of its status. If not set, the secret does not expire.", "type": "string", "format": "date-time", "examples": [ "2025-01-05T14:48:00Z" ] }, "id": { "description": "The unique identifier for this client secret. This ID is used to reference the secret in API requests for management operations like updating or deleting the secret.", "type": "string", "examples": [ "sec_1234abcd5678efgh" ] }, "last_used_time": { "description": "The timestamp when this secret was last used for authentication. This field helps track secret usage for security monitoring and identifying unused secrets that may be candidates for rotation.", "type": "string", "format": "date-time", "examples": [ "2024-02-15T10:30:00Z" ] }, "plain_secret": { "description": "The full plaintext secret value. This field is only populated when the secret is first created and is never stored by the server. It must be securely stored by the client application as it cannot be retrieved again.", "type": "string", "examples": [ "sec_1234567890abcdefghijklmnopqrstuvwxyz" ] }, "secret_suffix": { "description": "A suffix that helps identify this secret. This is the last few characters of the full secret value but is not sufficient for authentication. Helps identify which secret is being used in logs and debugging.", "type": "string", "examples": [ "xyzw" ] }, "status": { "description": "The current status of this secret. A secret must be ACTIVE to be used for authentication. INACTIVE secrets cannot be used for authentication but are retained for audit purposes.", "$ref": "#/components/schemas/clientsClientSecretStatus", "examples": [ "INACTIVE" ] }, "update_time": { "description": "The timestamp when this secret was last updated. This field is automatically updated by the server when the secret's status changes or other properties are modified.", "type": "string", "format": "date-time", "examples": [ "2024-01-10T09:12:00Z" ] } } }, "clientsClientSecretStatus": { "description": "ClientSecretStatus indicates whether a client secret can be used for authentication.\nACTIVE secrets can be used for authentication while INACTIVE secrets cannot.\n\n - INACTIVE: The secret is inactive and cannot be used for authentication", "type": "string", "enum": [ "INACTIVE" ] }, "clientsCreateOrganizationClientResponse": { "type": "object", "properties": { "client": { "description": "Details of the created client", "$ref": "#/components/schemas/clientsM2MClient" }, "plain_secret": { "description": "Client secret value (only returned once at creation)", "type": "string", "examples": [ "CdExsdErfccxDDssddfffgfeFHH1" ] } } }, "clientsCreateOrganizationClientSecretResponse": { "type": "object", "properties": { "plain_secret": { "description": "Client secret value (only returned once at creation)", "type": "string", "examples": [ "m2morg_client_secret_xyz123" ] }, "secret": { "description": "Details of the created client secret", "$ref": "#/components/schemas/clientsClientSecret" } } }, "clientsCustomClaim": { "type": "object", "properties": { "key": { "description": "The name of the custom claim. Must be between 1 and 128 characters. Use descriptive names that clearly indicate the claim's purpose.", "type": "string", "examples": [ "environment" ] }, "value": { "description": "The value of the custom claim. This value will be included in access tokens issued to the client.", "type": "string", "examples": [ "production" ] } } }, "clientsGetOrganizationClientResponse": { "type": "object", "properties": { "client": { "description": "Details of the requested client", "$ref": "#/components/schemas/clientsM2MClient" } } }, "clientsListOrganizationClientsResponse": { "description": "Response message containing a paginated list of API clients for the specified organization.", "type": "object", "title": "List Organization Clients Response", "properties": { "clients": { "description": "List of API client objects for the organization. Each client includes its configuration, metadata, and active secrets (without exposing actual secret values).", "type": "array", "title": "List of organization API clients", "items": { "type": "object", "$ref": "#/components/schemas/clientsM2MClient" } }, "next_page_token": { "description": "Pagination token for the next page of results. Use this token to fetch the next page.", "type": "string", "title": "Pagination token for the next page of results", "examples": [ "" ] }, "prev_page_token": { "description": "Pagination token for the previous page of results. Use this token to fetch the previous page.", "type": "string", "title": "Pagination token for the previous page of results", "examples": [ "" ] }, "total_size": { "description": "Total number of API clients in the organization.", "type": "integer", "format": "int64", "title": "Total number of clients in the organization", "examples": [ 30 ] } } }, "clientsM2MClient": { "type": "object", "properties": { "audience": { "description": "The intended recipients of access tokens issued to this client. Each audience value should be a URI that identifies an API or service.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://api.example.com" ] ] }, "client_id": { "description": "The unique identifier for this API client. This ID is used to identify the client in API requests and logs. It is automatically generated when the client is created and cannot be modified.", "type": "string", "examples": [ "m2morg_1231234233424344" ] }, "create_time": { "description": "The timestamp when this API client was created. This field is automatically set by the server and cannot be modified.", "type": "string", "format": "date-time", "examples": [ "2024-01-05T14:48:00Z" ] }, "custom_claims": { "description": "Additional claims included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/clientsCustomClaim" } }, "description": { "description": "A detailed description of the client's purpose and usage. This helps administrators understand what the client is used for.", "type": "string", "examples": [ "Service account for automated deployment processes" ] }, "expiry": { "description": "Expiry time in seconds for the token generated by the client", "type": "string", "format": "int64", "examples": [ 3600 ] }, "is_cimd": { "description": "Indicates if the client was created via Client ID Metadata Document (CIMD). CIMD clients can update their own configuration according to the CIMD specification.", "type": "boolean", "examples": [ false ] }, "is_dcr": { "description": "Indicates if the client was created via Dynamic Client Registration (DCR). Clients created through DCR may have different management and lifecycle policies compared to those created manually.", "type": "boolean", "examples": [ false ] }, "metadata_uri": { "description": "The URI to the client's metadata, which is utilized to obtain the client's configuration details", "type": "string", "examples": [ "https://example.com/client-metadata.json" ] }, "name": { "description": "The display name of the API client. This name helps identify the client in the dashboard and logs.", "type": "string", "examples": [ "GitHub Actions Deployment Service" ] }, "organization_id": { "description": "The ID of the organization that owns this API client. This ID is used to associate the client with the correct organization and enforce organization-specific access controls.", "type": "string", "examples": [ "org_1231234233424344" ] }, "redirect_uris": { "description": "The redirect URI for this API client. This URI is used in the OAuth 2.0 authorization flow to redirect users after authentication.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://example.com/callback" ] ] }, "resource_id": { "description": "The ID of the resource associated with this M2M client. This field is used to link the client to a specific resource in the system.", "type": "string", "examples": [ "app_1231234233424344" ] }, "scopes": { "description": "The OAuth 2.0 scopes granted to this client. These scopes determine what resources and actions the client can access.", "type": "array", "items": { "type": "string" }, "examples": [ [ "deploy:resources", "read:deployments" ] ] }, "secrets": { "description": "List of client secrets associated with this client. Each secret can be used for authentication, but only the most recently created secret is typically active. Secrets are stored securely and their values are never returned after creation.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/clientsClientSecret" } }, "update_time": { "description": "The timestamp when this API client was last updated. This field is automatically updated by the server whenever the client's configuration changes.", "type": "string", "format": "date-time", "examples": [ "2024-01-05T14:48:00Z" ] } } }, "clientsOrganizationClient": { "type": "object", "properties": { "audience": { "description": "The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://api.example.com/api/analytics", "https://deployment-api.acmecorp.com" ] ] }, "custom_claims": { "description": "Additional claims to be included in access tokens issued to this client. These claims provide context about the client and can be used for authorization decisions. Keep claims minimal to avoid increasing token size.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/clientsCustomClaim" }, "examples": [ [ { "key": "environment", "value": "production" }, { "key": "service", "value": "deployment" } ] ] }, "description": { "description": "A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it.", "type": "string", "examples": [ "Service account for GitHub Actions to deploy resources to production" ] }, "expiry": { "description": "Expiry time in seconds for the token generated by the client", "type": "string", "format": "int64", "examples": [ 3600 ] }, "name": { "description": "A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters.", "type": "string", "examples": [ "GitHub Actions Deployment Service" ] }, "scopes": { "description": "OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes.", "type": "array", "items": { "type": "string" }, "examples": [ [ "deploy:resources", "read:deployments" ] ] } } }, "clientsUpdateOrganizationClientResponse": { "type": "object", "properties": { "client": { "description": "Updated details of the client", "$ref": "#/components/schemas/clientsM2MClient" } } }, "commonsExternalIdentity": { "type": "object", "properties": { "connection_id": { "description": "Unique identifier for the external identity connection. Immutable and read-only.", "type": "string", "readOnly": true, "examples": [ "conn_1234abcd5678efgh" ] }, "connection_provider": { "description": "Type of the identity provider.", "$ref": "#/components/schemas/commonsIdentityProviderType", "readOnly": true, "examples": [ "GOOGLE" ] }, "connection_type": { "description": "Name of the external identity connection.", "type": "string", "readOnly": true, "examples": [ "OAUTH" ] }, "connection_user_id": { "description": "Unique identifier for the user in the external identity provider system. Immutable and read-only.", "type": "string", "readOnly": true, "examples": [ "ext_user_12345" ] }, "created_time": { "description": "Timestamp when this external identity connection was first created. Immutable and read-only.", "type": "string", "format": "date-time", "readOnly": true }, "is_social": { "description": "Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only.", "type": "boolean", "readOnly": true, "examples": [ true ] }, "last_login_time": { "description": "Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system.", "type": "string", "format": "date-time", "readOnly": true }, "last_synced_time": { "description": "Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system.", "type": "string", "format": "date-time", "readOnly": true } } }, "commonsIdentityProviderType": { "type": "string", "enum": [ "OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS" ] }, "commonsMembershipStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "PENDING_INVITE", "INVITE_EXPIRED" ] }, "commonsOrganizationMembership": { "type": "object", "properties": { "accepted_at": { "description": "Timestamp when the user accepted the invitation.", "type": "string", "format": "date-time" }, "created_at": { "description": "Timestamp when the invitation was created.", "type": "string", "format": "date-time" }, "display_name": { "description": "Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes.", "type": "string", "examples": [ "Acme Corporation" ] }, "expires_at": { "description": "Timestamp when the invitation expired.", "type": "string", "format": "date-time" }, "inviter_email": { "description": "ID of the user who invited this user.", "type": "string" }, "join_time": { "description": "Timestamp when the membership was created. Automatically set by the server.", "type": "string", "format": "date-time" }, "membership_status": { "$ref": "#/components/schemas/commonsMembershipStatus" }, "metadata": { "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "location": "nyc-office" } ] }, "name": { "description": "Organization name. This field stores the formal organization name used for identification and display purposes.", "type": "string", "examples": [ "AcmeCorp" ] }, "organization_id": { "description": "Unique identifier for the organization. Immutable and read-only.", "type": "string", "examples": [ "org_1234abcd5678efgh" ] }, "permissions": { "description": "Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform.", "type": "array", "items": { "type": "string" }, "examples": [ [ "read_projects", "write_tasks", "manage_users" ] ] }, "provisioning_method": { "description": "How the user was provisioned. \nPossible values: \n- `jit_using_sso` (Just-in-time provisioning during SSO login)\n- `allowed_email_domain` (User joined via allowed email domain matching)\n- `org_creator` (User created the organization)\n- `direct_provision` (User was directly provisioned via API or SCIM)\n- `invitation` (User was invited and accepted an invitation)", "type": "string" }, "roles": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/commonsRole" } } } }, "commonsRegionCode": { "type": "string", "enum": [ "US", "EU" ] }, "commonsRole": { "type": "object", "properties": { "display_name": { "description": "Human-readable name for the role", "type": "string", "examples": [ "Dev Team" ] }, "id": { "description": "Role ID", "type": "string", "readOnly": true, "examples": [ "role_79643236410327240" ] }, "name": { "description": "Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions.", "type": "string", "examples": [ "team_dev" ] } } }, "commonsTimeUnit": { "type": "string", "enum": [ "MINUTES", "HOURS", "DAYS" ] }, "commonsUserProfile": { "type": "object", "properties": { "custom_attributes": { "description": "Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. 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": [ { "department": "engineering", "security_clearance": "level2" } ] }, "email_verified": { "description": "Indicates if the user's email address has been verified. Automatically updated by the system.", "type": "boolean", "readOnly": true, "examples": [ true ] }, "external_identities": { "description": "List of external identity connections associated with the user profile.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/commonsExternalIdentity" }, "readOnly": true }, "family_name": { "description": "The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed.", "type": "string", "examples": [ "Doe" ] }, "gender": { "description": "The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations.", "type": "string", "examples": [ "male" ] }, "given_name": { "description": "The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed.", "type": "string", "examples": [ "John" ] }, "groups": { "description": "The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with.", "type": "array", "items": { "type": "string" }, "examples": [ [ "admin", "developer" ] ] }, "id": { "description": "Unique system-generated identifier for the user profile. Immutable and read-only.", "type": "string", "readOnly": true, "examples": [ "usr_profile_1234abcd5678efgh" ] }, "locale": { "description": "The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`.", "type": "string", "examples": [ "en-US" ] }, "metadata": { "description": "Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. 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": [ { "department": "engineering", "employee_type": "full-time", "idp_user_id": "12345" } ] }, "name": { "description": "The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given_name and family_name fields.", "type": "string", "examples": [ "John Michael Doe" ] }, "phone_number": { "description": "The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is optional.", "type": "string", "examples": [ "+14155552671" ] }, "phone_number_verified": { "description": "Indicates if the user's phone number has been verified. Automatically updated by the system.", "type": "boolean", "readOnly": true, "examples": [ true ] }, "picture": { "description": "The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform.", "type": "string", "examples": [ "https://example.com/avatar.jpg" ] }, "preferred_username": { "description": "The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed.", "type": "string", "examples": [ "johndoe" ] } } }, "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" ] } } }, "connectionsCodeChallengeType": { "type": "string", "enum": [ "NUMERIC", "ALPHANUMERIC" ] }, "connectionsConfigurationType": { "type": "string", "enum": [ "DISCOVERY", "MANUAL" ] }, "connectionsAppConnection": { "description": "A connection: your environment's settings for one connector.", "type": "object", "properties": { "auth_mode": { "description": "`USER`: each user authorizes their own account. `ORG_WIDE`: one admin-authorized account is shared.", "$ref": "#/components/schemas/connectionsConnectionAuthMode", "examples": [ "USER" ] }, "connection_mcp_url": { "description": "The URL of an MCP server that Scalekit hosts for this connection alone. Empty when the connection has none.", "type": "string", "examples": [ "https://yourapp.scalekit.dev/mcp/v3/connections/gmail-work" ] }, "connection_name": { "description": "The connection's name, such as `gmail-work`. Your code passes this name as `connection_name` when it creates connected accounts and runs tools.", "type": "string", "examples": [ "gmail-work" ] }, "create_time": { "description": "When the connection was created.", "type": "string", "format": "date-time", "readOnly": true, "examples": [ "2023-01-15T14:30:00Z" ] }, "google_dwd_config": { "description": "Google domain-wide delegation settings. Present only for `GOOGLE_DWD` connections.", "$ref": "#/components/schemas/connectionsGoogleDWDConfig" }, "id": { "description": "The connection's ID.", "type": "string", "examples": [ "conn_2123312131125533" ] }, "oauth_config": { "description": "OAuth settings. Present for connections that use OAuth.", "$ref": "#/components/schemas/connectionsAppOAuthConfig" }, "provider": { "description": "The connector this connection uses, such as `GMAIL`.", "type": "string", "examples": [ "GMAIL" ] }, "provider_configurations": { "description": "Settings for connectors that need extra ones, such as Slack.", "$ref": "#/components/schemas/connectionsAppProviderConfigurations" }, "type": { "description": "How users authenticate to the app, such as `OAUTH`. It comes from the connector and decides which settings object applies (`oauth_config` or `google_dwd_config`).", "$ref": "#/components/schemas/connectionsConnectionType", "examples": [ "OAUTH" ] }, "update_time": { "description": "When the connection was last changed.", "type": "string", "format": "date-time", "readOnly": true, "examples": [ "2023-02-20T09:15:30Z" ] } } }, "connectionsAppConnectionSummary": { "description": "A connection in a list, without its settings.", "type": "object", "properties": { "auth_mode": { "description": "`USER`: each user authorizes their own account. `ORG_WIDE`: one admin-authorized account is shared.", "$ref": "#/components/schemas/connectionsConnectionAuthMode" }, "connection_name": { "description": "The connection's name.", "type": "string" }, "create_time": { "description": "When the connection was created.", "type": "string", "format": "date-time" }, "id": { "description": "The connection's ID.", "type": "string", "examples": [ "conn_2123312131125533" ] }, "provider": { "description": "The connector this connection uses, such as `GMAIL`.", "type": "string" }, "type": { "description": "How users authenticate to the app, such as `OAUTH`.", "$ref": "#/components/schemas/connectionsConnectionType" } } }, "connectionsAppConnectionUpdate": { "description": "The settings to change. Send only what you want to change.", "type": "object", "properties": { "connection_name": { "description": "A new name for the connection, such as `gmail-prod`: letters, numbers and hyphens, unique in the environment. Your code refers to the connection by this name, so update the `connection_name` it passes when you rename one.", "type": "string", "examples": [ "gmail-prod" ] }, "google_dwd_config": { "description": "Google domain-wide delegation settings to change. Only for connections whose `type` is `GOOGLE_DWD`.", "$ref": "#/components/schemas/connectionsGoogleDWDConfig" }, "oauth_config": { "description": "OAuth settings to change, such as `client_id`, `client_secret` and `scopes`. For connections that use OAuth, such as `type` `OAUTH`.", "$ref": "#/components/schemas/connectionsAppOAuthConfig" }, "provider_configurations": { "description": "Connector-specific settings to change, for the connectors listed on each field. `provider_domain` can only be set when you create the connection.", "$ref": "#/components/schemas/connectionsAppProviderConfigurations" } } }, "connectionsAppOAuthConfig": { "description": "OAuth settings for the connection.", "type": "object", "properties": { "access_type": { "description": "The `access_type` value sent to the provider, such as `offline`.", "type": "string", "examples": [ "offline" ] }, "authorize_uri": { "description": "The provider's authorization URL.", "type": "string", "examples": [ "https://youridp.com/service/oauth/authorize" ] }, "client_id": { "description": "The client ID of the OAuth app you registered with the provider, such as `123456789012-abc123def456.apps.googleusercontent.com` for a Google app. Get it from the provider's developer console when you create the app (for Gmail: Google Cloud console, **APIs & Services** > **Credentials**, an OAuth client ID of type web application), and add this connection's `redirect_uri` to the app as an authorized redirect URI. Each connector's page under [Connectors](/agentkit/connectors/) has the steps for that provider.", "type": "string", "examples": [ "123456789012-abc123def456.apps.googleusercontent.com" ] }, "client_secret": { "description": "The client secret of the same OAuth app, from the provider's developer console. Write-only: responses show it masked, such as `********abcd`. Leave it out to keep the stored secret.", "type": "string", "examples": [ "GOCSPX-your-client-secret" ] }, "extra_authorize_params": { "description": "Extra query parameters to add to the provider's authorization URL, as name-value pairs, such as `{\"hd\": \"example.com\"}`, which asks Google to suggest accounts from that domain. Check the provider's OAuth documentation for the parameters it accepts. Send `{}` to clear them.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "hd": "example.com" } ] }, "optional_scopes": { "description": "A second set of scopes, for providers that take them in a separate authorization parameter, such as Slack's `user_scope`. Set `field_name` to that parameter's name and `scopes` to its values.", "$ref": "#/components/schemas/connectionsOptionalScopes" }, "pkce_enabled": { "description": "Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE.", "type": "boolean", "examples": [ true ] }, "prompt": { "description": "The `prompt` value sent to the provider, which controls whether the user signs in or consents again, such as `consent`. Send an empty string to send no `prompt`.", "type": "string", "examples": [ "consent" ] }, "redirect_uri": { "description": "The redirect URI to add to the app you registered with the provider, as an authorized redirect URI. Scalekit sets it; you can't change it.", "type": "string", "examples": [ "https://yourapp.scalekit.dev/sso/v1/oauth/conn_24832952112323587/callback" ] }, "required_optional_scopes": { "description": "Scopes from `optional_scopes.scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `optional_scopes.scopes`.", "type": "array", "items": { "type": "string" }, "examples": [ [ "search:read" ] ] }, "required_scopes": { "description": "Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`, such as the read scope your tools always need. Each must also be in `scopes`, or the request fails with `400`.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://www.googleapis.com/auth/gmail.readonly" ] ] }, "scope_selection_allowed": { "description": "Set to `true` to let users choose which of the `scopes` to grant when they connect. Scopes in `required_scopes` stay selected.", "type": "boolean", "examples": [ true ] }, "scopes": { "description": "The OAuth scopes users grant when they connect, such as `https://www.googleapis.com/auth/gmail.readonly` for Gmail. A list you send replaces the whole current list, so include the scopes you want to keep. To build it, start from the current scopes in [Get a connection](/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](/agentkit/bring-your-own-connector/create-connector/#list-connectors) with `identifier` set to the connector, such as `GMAIL`, and read `auth_patterns[].oauth_config.available_scopes[].scope`. You can also add a scope that isn't listed there, using the exact scope string from the provider's own documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes).", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.send" ] ] }, "token_access_type": { "description": "The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`.", "type": "string", "examples": [ "offline" ] }, "token_endpoint_auth_method": { "description": "How Scalekit sends client credentials to the provider's token URL. `DEFAULT` lets Scalekit choose.", "$ref": "#/components/schemas/AppOAuthConfigTokenEndpointAuthMethod", "examples": [ "BASIC_AUTH" ] }, "token_uri": { "description": "The provider's token URL.", "type": "string", "examples": [ "https://youridp.com/service/oauth/token" ] }, "use_scalekit_creds": { "description": "Set to `true` to use Scalekit's own OAuth app instead of yours, for connectors that offer one; otherwise the request fails with `400`. Sending your own `client_id` or `client_secret` sets it to `false` unless you also send it.", "type": "boolean", "examples": [ true ] }, "user_info_uri": { "description": "The provider's user info URL.", "type": "string", "examples": [ "https://youridp.com/service/oauth/userinfo" ] } } }, "connectionsAppProviderConfigurations": { "description": "Settings for connectors that need extra ones.", "type": "object", "properties": { "googleads_developer_token": { "description": "Google Ads only: your Google Ads API developer token. See Google's [Obtain a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). Responses show it masked.", "type": "string", "examples": [ "ABcDeFgHiJkLmNoPqRsTuV" ] }, "microsoft_tenant_id": { "description": "Microsoft connectors only: the ID of your Microsoft Entra tenant, from the **Overview** page of Microsoft Entra ID in the Azure portal.", "type": "string", "examples": [ "72f988bf-86f1-41af-91ab-2d7cd011db47" ] }, "provider_domain": { "description": "The regional domain that hosts your account, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region, for connectors that need one. Set it when you create the connection; it can't be changed later and isn't returned.", "type": "string", "examples": [ "mcp-eu.mixpanel.com" ] }, "slack_connection_type": { "description": "Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects.", "type": "string", "enum": [ "BOT", "USER" ], "examples": [ "USER" ] }, "smart_fhir_aud": { "description": "SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in.", "type": "string", "examples": [ "https://fhir.example.com/r4" ] }, "smart_fhir_domain": { "description": "SMART on FHIR only: the domain of the FHIR server.", "type": "string", "examples": [ "fhir.example.com" ] }, "trello_app_name": { "description": "Trello only: the name of your Trello app, which Trello shows users when they authorize it.", "type": "string", "examples": [ "My Trello App" ] } } }, "connectionsConnectionAuthMode": { "description": "How users authorize the connection: `USER` or `ORG_WIDE`.", "type": "string", "enum": [ "USER", "ORG_WIDE" ] }, "connectionsCreateAppConnectionResponse": { "description": "The connection that was created.", "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/connectionsAppConnection", "description": "The connection that was created." } } }, "connectionsGetAppConnectionResponse": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/connectionsAppConnection", "description": "The connection." } }, "description": "The connection." }, "connectionsListAppConnectionSummariesResponse": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/connectionsAppConnectionSummary" }, "description": "The connections on this page, newest first." }, "next_page_token": { "type": "string", "description": "Pass as `page_token` to get the next page. Empty on the last page." }, "prev_page_token": { "type": "string", "description": "Pass as `page_token` to get the previous page." }, "total_size": { "description": "The number of connections that match.", "type": "integer", "format": "int64" } } }, "connectionsUpdateAppConnectionResponse": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/connectionsAppConnection", "description": "The connection with its new settings." } }, "description": "The connection with its new settings." }, "v1connectionsCreateAppConnection": { "type": "object", "properties": { "auth_mode": { "description": "`USER` (default): each user authorizes their own account. `ORG_WIDE`: one admin authorizes an account that every user shares. You can't change it after the connection is created.", "$ref": "#/components/schemas/connectionsConnectionAuthMode", "examples": [ "USER" ] }, "connection_name": { "description": "A name for the connection, such as `gmail-work`: letters, numbers and hyphens, unique in the environment. Your code passes this name as `connection_name` when it creates connected accounts and runs tools. Scalekit generates one if you leave it out.", "type": "string", "examples": [ "gmail-work" ] }, "provider": { "description": "The connector's identifier, such as `GMAIL`. To find a connector's identifier, call [List connectors](/agentkit/bring-your-own-connector/create-connector/#list-connectors) and read `identifier`.", "type": "string", "examples": [ "GMAIL" ] }, "provider_configurations": { "description": "Extra settings, only for the connectors named on each field, such as `provider_domain` for a connector with regional domains.", "$ref": "#/components/schemas/connectionsAppProviderConfigurations" } }, "description": "The connection to create." }, "AppOAuthConfigTokenEndpointAuthMethod": { "description": "How Scalekit sends client credentials to the provider's token URL.", "type": "string", "enum": [ "NONE", "BASIC_AUTH", "REQUEST_BODY", "DEFAULT" ] }, "connectionsConnection": { "type": "object", "properties": { "attribute_mapping": { "description": "Maps identity provider attributes to user profile fields. For example, {'email': 'user.mail', 'name': 'user.displayName'}.", "type": "object", "additionalProperties": { "type": "string" } }, "configuration_type": { "description": "How the connection was configured: DISCOVERY (automatic configuration) or MANUAL (administrator configured)", "$ref": "#/components/schemas/connectionsConfigurationType", "examples": [ "MANUAL" ] }, "debug_enabled": { "description": "Enables testing mode that allows non-HTTPS endpoints. Should only be enabled in development environments, never in production.", "type": "boolean", "examples": [ true ] }, "domains": { "description": "Domain associated with this connection, used for domain-based authentication flows.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/domainsDomain" }, "examples": [ [ { "name": "example.com" } ] ] }, "enabled": { "description": "Controls whether users can sign in using this connection. When false, the connection exists but cannot be used for authentication.", "type": "boolean", "examples": [ false ] }, "google_dwd_config": { "description": "Configuration details for Google Domain-Wide Delegation. Present only when type is GOOGLE_DWD.", "$ref": "#/components/schemas/connectionsGoogleDWDConfig" }, "id": { "description": "Unique identifier for this connection. Used in API calls to reference this specific connection.", "type": "string", "examples": [ "conn_2123312131125533" ] }, "key_id": { "description": "Alternative identifier for this connection, typically used in frontend applications or URLs.", "type": "string" }, "mcp_server_url": { "description": "URL of the MCP server for this connection. Agents can point directly at this URL to access only the tools for this connection, without needing to call list_connections or execute_tool with a connection_name. Empty when the MCP virtual servers feature is not enabled for this environment.", "type": "string", "readOnly": true, "examples": [ "https://acmecorp.scalekit.dev/mcp/v3/connections/gmail_work" ] }, "oauth_config": { "description": "Configuration details for OAuth connections. Present only when type is OAUTH.", "$ref": "#/components/schemas/connectionsOAuthConnectionConfig" }, "oidc_config": { "description": "Configuration details for OpenID Connect (OIDC) connections. Present only when type is OIDC.", "$ref": "#/components/schemas/connectionsOIDCConnectionConfig" }, "organization_id": { "description": "Identifier of the organization that owns this connection. Connections are typically scoped to a single organization.", "type": "string", "examples": [ "org_2123312131125533" ] }, "passwordless_config": { "description": "Configuration details for Magic Link authentication. Present only when type is MAGIC_LINK.", "$ref": "#/components/schemas/connectionsPasswordLessConfig" }, "provider": { "description": "Identity provider service that handles authentication (such as OKTA, Google, Azure AD, or a custom provider)", "$ref": "#/components/schemas/connectionsConnectionProvider", "examples": [ "OKTA" ] }, "provider_key": { "description": "Key ID of the identity provider service that handles authentication", "type": "string", "examples": [ "google" ] }, "saml_config": { "description": "Configuration details for SAML connections. Present only when type is SAML.", "$ref": "#/components/schemas/connectionsSAMLConnectionConfigResponse" }, "static_config": { "description": "Static configuration for custom connections. Present only when type is BASIC, BEARER, API_KEY, or custom.", "$ref": "#/components/schemas/connectionsStaticAuthConfig" }, "status": { "description": "Current configuration status of the connection. Possible values include IN_PROGRESS, CONFIGURED, and ERROR.", "$ref": "#/components/schemas/connectionsConnectionStatus", "readOnly": true, "examples": [ "IN_PROGRESS" ] }, "test_connection_uri": { "description": "URI that can be used to test this connection. Visit this URL to verify the connection works correctly.", "type": "string", "examples": [ "https://auth.example.com/test-connection/conn_2123312131125533" ] }, "type": { "description": "Authentication protocol used by this connection. Possible values: OIDC (OpenID Connect), SAML, PASSWORD, OAUTH, PASSWORDLESS, BASIC, BEARER, API_KEY, WEBAUTHN, OAUTH_M2M, TRELLO_OAUTH1, GOOGLE_DWD, TRUSTED_IDP, SMART_FHIR, or NO_AUTH (no credentials required).", "$ref": "#/components/schemas/connectionsConnectionType", "examples": [ "OIDC" ] }, "webauthn_config": { "description": "Configuration details for WebAuthn (passkeys). Present only when type is WEBAUTHN.", "$ref": "#/components/schemas/connectionsWebAuthConfiguration" } } }, "connectionsConnectionProvider": { "type": "string", "enum": [ "OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "PING_IDENTITY", "JUMPCLOUD", "CUSTOM", "GITHUB", "GITLAB", "LINKEDIN", "SALESFORCE", "MICROSOFT", "IDP_SIMULATOR", "SCALEKIT", "ADFS" ] }, "connectionsConnectionStatus": { "type": "string", "enum": [ "DRAFT", "IN_PROGRESS", "COMPLETED" ] }, "connectionsConnectionType": { "type": "string", "enum": [ "OIDC", "SAML", "PASSWORD", "OAUTH", "PASSWORDLESS", "BASIC", "BEARER", "API_KEY", "WEBAUTHN", "OAUTH_M2M", "TRELLO_OAUTH1", "GOOGLE_DWD", "TRUSTED_IDP", "SMART_FHIR", "NO_AUTH" ] }, "connectionsGetConnectionResponse": { "type": "object", "properties": { "connection": { "description": "Complete connection details including provider configuration, protocol settings, status, and all metadata. Contains everything needed to understand the connection's current state.", "$ref": "#/components/schemas/connectionsConnection" } } }, "connectionsGoogleDWDConfig": { "type": "object", "properties": { "required_scopes": { "description": "Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://www.googleapis.com/auth/gmail.readonly" ] ] }, "scope_selection_allowed": { "description": "Set to `true` to let users choose which of the `scopes` to grant when they connect.", "type": "boolean", "examples": [ true ] }, "scopes": { "description": "The Google scopes to request, such as `https://www.googleapis.com/auth/gmail.readonly`. A list you send replaces the current one. Authorize the same scopes for the service account's client ID in the Google Workspace Admin console, under **Security** > **Access and data control** > **API controls** > **Manage domain wide delegation**.", "type": "array", "items": { "type": "string" }, "examples": [ [ "https://www.googleapis.com/auth/gmail.readonly" ] ] }, "service_account_json": { "description": "The contents of the service account's JSON key file, as a string. Create the key in the Google Cloud console under **IAM & Admin** > **Service accounts** > your service account > **Keys** > **Add key**. Responses show it masked.", "type": "string", "examples": [ "{\"type\":\"service_account\",\"project_id\":\"my-project\",\"private_key_id\":\"0123456789abcdef\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\nMIIEvQ...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"dwd-sa@my-project.iam.gserviceaccount.com\",\"client_id\":\"123456789012345678901\"}" ] }, "token_uri": { "description": "Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`.", "type": "string" } } }, "connectionsIDPCertificate": { "type": "object", "properties": { "certificate": { "description": "IDP Certificate", "type": "string" }, "create_time": { "description": "Certificate Creation Time", "type": "string", "format": "date-time", "examples": [ "2021-09-01T00:00:00Z" ] }, "expiry_time": { "description": "Certificate Expiry Time", "type": "string", "format": "date-time", "examples": [ "2021-09-01T00:00:00Z" ] }, "id": { "description": "Certificate ID", "type": "string", "examples": [ "cert_123123123123" ] }, "issuer": { "description": "Certificate Issuer", "type": "string", "examples": [ "https://youridp.com/service/saml" ] } } }, "connectionsListConnection": { "type": "object", "properties": { "domains": { "description": "List of domains configured with this connection", "type": "array", "items": { "type": "string" }, "examples": [ [ "yourapp.com", "yourworkspace.com" ] ] }, "enabled": { "description": "Whether the connection is currently active for organization users", "type": "boolean", "examples": [ false ] }, "id": { "description": "Unique identifier of the connection", "type": "string", "examples": [ "conn_2123312131125533" ] }, "key_id": { "description": "Alternative identifier for this connection, typically used in frontend applications or URLs", "type": "string", "examples": [ "conn_2123312131125533" ] }, "mcp_server_url": { "description": "MCP virtual server URL for this connection. Agents can point directly at this URL to access only the tools for this connection, without needing to call list_connections or execute_tool with a connection_name. Empty when the MCP virtual servers feature is not enabled for this environment.", "type": "string", "readOnly": true, "examples": [ "https://acmecorp.scalekit.dev/mcp/v3/connections/gmail_work" ] }, "organization_id": { "description": "Unique identifier of the organization that owns this connection", "type": "string", "examples": [ "org_2123312131125533" ] }, "organization_name": { "description": "Name of the organization of the connection", "type": "string", "examples": [ "Your Organization" ] }, "provider": { "description": "Identity provider type (e.g., OKTA, Google, Azure AD)", "$ref": "#/components/schemas/connectionsConnectionProvider", "examples": [ "CUSTOM" ] }, "provider_key": { "description": "Key ID of the identity provider service that handles authentication", "type": "string", "examples": [ "google" ] }, "status": { "description": "Current configuration status of the connection", "$ref": "#/components/schemas/connectionsConnectionStatus", "readOnly": true, "examples": [ "IN_PROGRESS" ] }, "type": { "description": "Authentication protocol used by the connection", "$ref": "#/components/schemas/connectionsConnectionType", "examples": [ "OIDC" ] } } }, "connectionsListConnectionsResponse": { "type": "object", "properties": { "connections": { "description": "List of connections matching the request criteria", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/connectionsListConnection" } } } }, "connectionsNameIdFormat": { "type": "string", "enum": [ "UNSPECIFIED", "EMAIL", "TRANSIENT", "PERSISTENT" ] }, "connectionsOAuthConnectionConfig": { "type": "object", "properties": { "access_type": { "description": "Access Type", "type": "string", "examples": [ "offline" ] }, "app_name": { "description": "Application name used by providers that require it as an authorize query parameter (e.g., Trello's app_name).", "type": "string", "examples": [ "My Trello App" ] }, "authorize_uri": { "description": "Authorize URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/authorize" ] }, "client_id": { "description": "Client ID", "type": "string", "examples": [ "oauth_client_id" ] }, "client_secret": { "description": "Client Secret", "type": "string", "examples": [ "oauth_client_secret" ] }, "custom_scope_name": { "description": "Custom Scope Name", "type": "string", "examples": [ "user_scope" ] }, "extensions": { "description": "OAuth extension profiles for this connection, such as SMART on FHIR. Carries typed extension configuration plus a generic escape hatch for provider-specific authorize query parameters.", "$ref": "#/components/schemas/connectionsOauthExtensions" }, "googleads_developer_token": { "description": "Google Ads API developer token, issued once per company from the Google Ads API Center. Applies only to the GOOGLEADS provider, which requires this static application-level credential on every REST call alongside the user's OAuth access token. Configure it once per connection; Scalekit stores it encrypted and injects it as the developer-token header at tool-call time, so individual tool calls never carry it. Read responses return the value masked, showing only the last four characters.", "type": "string", "examples": [ "ABcDeFgHiJkLmNoPqRsTuV" ] }, "is_cimd": { "description": "Indicates whether this connection was registered using Client ID Metadata Document (CIMD) instead of Dynamic Client Registration.", "type": "boolean", "readOnly": true, "examples": [ true ] }, "optional_scopes": { "description": "Optional scopes configuration for identity providers that support or require additional scopes to be sent in a custom field during authentication requests.", "$ref": "#/components/schemas/connectionsOptionalScopes" }, "pkce_enabled": { "description": "PKCE Enabled", "type": "boolean", "examples": [ true ] }, "prompt": { "description": "Prompt for the user", "type": "string", "examples": [ "none" ] }, "redirect_uri": { "description": "Redirect URI", "type": "string", "examples": [ "https://yourapp.com/service/oauth/redirect" ] }, "scopes": { "description": "OIDC Scopes", "type": "array", "items": { "type": "string" }, "examples": [ [ "openid", "profile" ] ] }, "sync_user_profile_on_login": { "description": "Indicates whether user profiles should be synchronized with the identity provider upon each log-in.", "type": "boolean", "examples": [ true ] }, "tenant_id": { "description": "Microsoft Entra tenant ID. Required when using a single-tenant or multi-tenant app registered in Microsoft Entra. Leave empty to use the common endpoint.", "type": "string", "examples": [ "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ] }, "token_access_type": { "description": "Token Access Type", "type": "string", "examples": [ "offline" ] }, "token_endpoint_auth_method": { "description": "How client credentials are sent to the token endpoint during the authorization_code exchange. One of \"client_secret_basic\" (HTTP Basic Auth, required by some providers e.g. Reddit), \"client_secret_post\" (POST body params), or \"none\". Leave unset to keep the current default (POST body params). Does not affect token refresh, which currently uses a separate auto-detected auth style.", "type": "string", "examples": [ "client_secret_basic" ] }, "token_uri": { "description": "Token URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/token" ] }, "use_platform_creds": { "description": "Use Scalekit credentials", "type": "boolean", "examples": [ true ] }, "user_info_uri": { "description": "User Info URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/userinfo" ] } } }, "connectionsOIDCConnectionConfig": { "type": "object", "properties": { "authorize_uri": { "description": "Authorize URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/authorize" ] }, "backchannel_logout_redirect_uri": { "description": "backchannel logout redirect uri where idp sends logout_token", "type": "string", "readOnly": true, "examples": [ "https://yourapp.com/sso/v1/oidc/conn_1234/backchannel-logout" ] }, "client_id": { "description": "Client ID", "type": "string", "examples": [ "oauth_client_id" ] }, "client_secret": { "description": "Client Secret", "type": "string", "examples": [ "oauth_client_secret" ] }, "discovery_endpoint": { "description": "Discovery Endpoint", "type": "string", "examples": [ "https://youridp.com/service/oauth/.well-known/openid-configuration" ] }, "idp_logout_required": { "description": "Enable IDP logout", "type": "boolean", "examples": [ true ] }, "issuer": { "description": "Issuer URL", "type": "string", "examples": [ "https://youridp.com/service/oauth" ] }, "jit_provisioning_with_sso_enabled": { "description": "Indicates if Just In Time user provisioning is enabled for the connection", "type": "boolean", "examples": [ true ] }, "jwks_uri": { "description": "JWKS URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/jwks" ] }, "pkce_enabled": { "description": "PKCE Enabled", "type": "boolean", "examples": [ true ] }, "post_logout_redirect_uri": { "description": "post logout redirect uri", "type": "string", "readOnly": true, "examples": [ "https://yourapp.com/sso/v1/oidc/conn_1234/logout/callback" ] }, "redirect_uri": { "description": "Redirect URI", "type": "string", "examples": [ "https://yourapp.com/sso/v1/oidc/conn_1234/callback" ] }, "scopes": { "description": "OIDC Scopes", "type": "array", "items": { "$ref": "#/components/schemas/connectionsOIDCScope" }, "examples": [ [ "openid", "profile" ] ] }, "sync_user_profile_on_login": { "description": "Indicates whether user profiles should be synchronized with the identity provider upon each log-in.", "type": "boolean", "examples": [ true ] }, "token_auth_type": { "description": "Token Auth Type", "$ref": "#/components/schemas/connectionsTokenAuthType", "examples": [ "URL_PARAMS" ] }, "token_uri": { "description": "Token URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/token" ] }, "user_info_uri": { "description": "User Info URI", "type": "string", "examples": [ "https://youridp.com/service/oauth/userinfo" ] } } }, "connectionsOIDCScope": { "type": "string", "enum": [ "openid", "profile", "email", "address", "phone" ] }, "connectionsOauthExtensions": { "description": "OauthExtensions groups OAuth extension-profile configuration for a connection.\nSignificant profiles (e.g. SMART on FHIR) get a typed sub-message; the long tail\nof one-off authorize parameters uses extra_authorize_params.", "type": "object", "properties": { "extra_authorize_params": { "description": "Provider-specific query parameters added to the authorization request. Reserved OAuth/OIDC parameters (client_id, redirect_uri, scope, state, code_challenge, aud, and similar) are rejected.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "custom_param": "value" } ] }, "smart": { "description": "SMART on FHIR (SMART App Launch) configuration. Set this to issue a SMART-compliant standalone launch authorization request to a FHIR server.", "$ref": "#/components/schemas/connectionsSmartConfig" } } }, "connectionsOptionalScopes": { "type": "object", "properties": { "field_name": { "description": "Name of the field in which scope should be sent in the authentication request. This is required by some identity providers that expect scopes to be sent in a custom field instead of the standard 'scope' parameter.", "type": "string", "examples": [ "optional_scope or bot_scope" ] }, "scopes": { "description": "List of optional scopes that can be requested during authentication", "type": "array", "items": { "type": "string" }, "examples": [ [ "scope1", "scope2" ] ] } } }, "connectionsPasswordLessConfig": { "type": "object", "properties": { "code_challenge_length": { "description": "Code Challenge Length", "type": "integer", "format": "int64", "examples": [ 6 ] }, "code_challenge_type": { "description": "Code Challenge Type", "$ref": "#/components/schemas/connectionsCodeChallengeType", "examples": [ "NUMERIC" ] }, "enforce_same_browser_origin": { "description": "Enforce Same Browser Origin", "type": "boolean", "examples": [ true ] }, "frequency": { "description": "Link Frequency", "type": "integer", "format": "int64", "examples": [ 1 ] }, "regenerate_passwordless_credentials_on_resend": { "description": "Regenerate the ", "type": "boolean", "examples": [ true ] }, "type": { "description": "Passwordless Type", "$ref": "#/components/schemas/connectionsPasswordlessType", "examples": [ "LINK" ] }, "validity": { "description": "Link Validity in Seconds", "type": "integer", "format": "int64", "examples": [ 600 ] } } }, "connectionsPasswordlessType": { "type": "string", "enum": [ "LINK", "OTP", "LINK_OTP" ] }, "connectionsRequestBinding": { "type": "string", "enum": [ "HTTP_POST", "HTTP_REDIRECT" ] }, "connectionsSAMLConnectionConfigResponse": { "type": "object", "properties": { "allow_idp_initiated_login": { "description": "Allow IDP Initiated Login", "type": "boolean", "examples": [ true ] }, "assertion_encrypted": { "description": "Assertion Encrypted", "type": "boolean", "examples": [ true ] }, "certificate_id": { "description": "Certificate ID", "type": "string", "examples": [ "cer_35585423166144613" ] }, "default_redirect_uri": { "description": "Default Redirect URI", "type": "string", "examples": [ "https://yourapp.com/service/saml/redirect" ] }, "force_authn": { "description": "Force Authn", "type": "boolean", "examples": [ true ] }, "idp_certificates": { "description": "IDP Certificates", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/connectionsIDPCertificate" } }, "idp_entity_id": { "description": "IDP Entity ID", "type": "string", "examples": [ "https://youridp.com/service/saml" ] }, "idp_metadata_url": { "description": "IDP Metadata URL", "type": "string", "examples": [ "https://youridp.com/service/saml/metadata" ] }, "idp_name_id_format": { "description": "IDP Name ID Format", "$ref": "#/components/schemas/connectionsNameIdFormat", "examples": [ "EMAIL" ] }, "idp_slo_request_binding": { "description": "IDP SLO Request Binding", "$ref": "#/components/schemas/connectionsRequestBinding", "examples": [ "HTTP_POST" ] }, "idp_slo_required": { "description": "Enable IDP logout", "type": "boolean", "examples": [ true ] }, "idp_slo_url": { "description": "IDP SLO URL", "type": "string", "examples": [ "https://youridp.com/service/saml/slo" ] }, "idp_sso_request_binding": { "description": "IDP SSO Request Binding", "$ref": "#/components/schemas/connectionsRequestBinding", "examples": [ "HTTP_POST" ] }, "idp_sso_url": { "description": "IDP SSO URL", "type": "string", "examples": [ "https://youridp.com/service/saml/sso" ] }, "jit_provisioning_with_sso_enabled": { "description": "Indicates if Just In Time user provisioning is enabled for the connection", "type": "boolean", "examples": [ true ] }, "saml_signing_option": { "description": "SAML Signing Option", "$ref": "#/components/schemas/connectionsSAMLSigningOptions", "examples": [ "SAML_ONLY_RESPONSE_SIGNING" ] }, "sp_assertion_url": { "description": "SP Assertion URL", "type": "string", "examples": [ "https://youridp.com/service/saml/assertion" ] }, "sp_entity_id": { "description": "SP Entity ID", "type": "string", "examples": [ "https://yourapp.com/service/saml" ] }, "sp_metadata_url": { "description": "SP Metadata URL", "type": "string", "examples": [ "https://youridp.com/service/saml/metadata" ] }, "sp_slo_url": { "description": "Service Provider SLO url", "type": "string", "readOnly": true, "examples": [ "https://yourapp.com/sso/v1/saml/conn_1234/slo/callback" ] }, "sync_user_profile_on_login": { "description": "Indicates whether user profiles should be synchronized with the identity provider upon each log-in.", "type": "boolean", "examples": [ true ] }, "ui_button_title": { "description": "UI Button Title", "type": "string", "examples": [ "Login with SSO" ] }, "want_request_signed": { "description": "Want Request Signed", "type": "boolean", "examples": [ true ] } } }, "connectionsSAMLSigningOptions": { "type": "string", "title": "enums all", "enum": [ "NO_SIGNING", "SAML_ONLY_RESPONSE_SIGNING", "SAML_ONLY_ASSERTION_SIGNING", "SAML_RESPONSE_ASSERTION_SIGNING", "SAML_RESPONSE_OR_ASSERTION_SIGNING" ] }, "connectionsSmartConfig": { "description": "SmartConfig holds SMART on FHIR (SMART App Launch) parameters.", "type": "object", "properties": { "aud": { "description": "FHIR resource server base URL, sent as the required 'aud' authorization parameter per the SMART App Launch specification. Binds the issued token to the intended FHIR server.", "type": "string", "examples": [ "https://fhir.example.com/r4" ] }, "domain": { "description": "FHIR server domain for the SMART on FHIR connection. Stored alongside the audience and editable through the connection update API.", "type": "string", "examples": [ "fhir.example.com" ] } } }, "connectionsStaticAuthConfig": { "type": "object", "properties": { "static_config": { "type": "object" } } }, "connectionsToggleConnectionResponse": { "type": "object", "properties": { "enabled": { "description": "Current state of the connection after the operation. True means the connection is now enabled and can be used for authentication.", "type": "boolean", "examples": [ true ] }, "error_message": { "description": "Error message if the operation fails", "type": "string", "examples": [ "placeholder" ] } } }, "connectionsTokenAuthType": { "type": "string", "enum": [ "URL_PARAMS", "BASIC_AUTH" ] }, "connectionsWebAuthConfiguration": { "type": "object", "title": "WebAuthConfiguration defines WebAuthn (passkeys) configuration limited to RP and Attestation", "properties": { "attestation": { "$ref": "#/components/schemas/WebAuthConfigurationAttestation" }, "authenticator_selection": { "$ref": "#/components/schemas/WebAuthConfigurationAuthenticatorSelection" }, "authenticators": { "$ref": "#/components/schemas/WebAuthConfigurationAuthenticators" }, "enable_auto_registration": { "description": "Enable auto registration for WebAuthn", "type": "boolean" }, "enable_conditional_login": { "description": "Allow autofill of passkeys in login page", "type": "boolean" }, "rp": { "$ref": "#/components/schemas/WebAuthConfigurationRp" }, "show_passkey_button": { "description": "Show passkey button on login screen", "type": "boolean" }, "timeout": { "$ref": "#/components/schemas/WebAuthConfigurationTimeout" } } }, "directoriesAttributeMapping": { "type": "object", "properties": { "key": { "type": "string" }, "map_to": { "type": "string" } } }, "directoriesAttributeMappings": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesAttributeMapping" } } } }, "directoriesDirectory": { "type": "object", "properties": { "attribute_mappings": { "description": "Mappings between directory attributes and Scalekit user and group attributes", "$ref": "#/components/schemas/directoriesAttributeMappings" }, "directory_endpoint": { "description": "The endpoint URL generated by Scalekit for synchronizing users and groups from the Directory Provider", "type": "string", "examples": [ "https://yourapp.scalekit.com/api/v1/directoies/dir_123212312/scim/v2" ] }, "directory_provider": { "description": "Identity provider connected to this directory", "$ref": "#/components/schemas/directoriesDirectoryProvider", "examples": [ "OKTA" ] }, "directory_type": { "description": "Type of the directory, indicating the protocol or standard used for synchronization", "$ref": "#/components/schemas/directoriesDirectoryType", "examples": [ "SCIM" ] }, "email": { "description": "Email Id associated with Directory whose access will be used for polling", "type": "string", "examples": [ "john.doe@scalekit.cloud" ] }, "enabled": { "description": "Indicates whether the directory is currently enabled and actively synchronizing users and groups", "type": "boolean", "examples": [ true ] }, "groups_tracked": { "description": "It indicates if all groups are tracked or select groups are tracked", "type": "string", "examples": [ "ALL" ] }, "id": { "description": "Unique identifier of the directory", "type": "string", "examples": [ "dir_121312434123312" ] }, "last_synced_at": { "description": "Timestamp of the last successful synchronization of users and groups from the Directory Provider", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] }, "name": { "description": "Name of the directory, typically representing the connected Directory provider", "type": "string", "examples": [ "Azure AD" ] }, "organization_id": { "description": "Unique identifier of the organization to which the directory belongs", "type": "string", "examples": [ "org_121312434123312" ] }, "role_assignments": { "description": "Role assignments associated with the directory, defining group based role assignments", "$ref": "#/components/schemas/directoriesRoleAssignments" }, "secrets": { "description": "List of secrets used for authenticating and synchronizing with the Directory Provider", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesSecret" } }, "stats": { "description": "Statistics and metrics related to the directory, such as synchronization status and error counts", "$ref": "#/components/schemas/directoriesStats" }, "status": { "description": "Directory Status", "type": "string", "examples": [ "IN_PROGRESS" ] }, "total_groups": { "description": "Total number of groups in the directory", "type": "integer", "format": "int32", "examples": [ 10 ] }, "total_users": { "description": "Total number of users in the directory", "type": "integer", "format": "int32", "examples": [ 10 ] } } }, "directoriesDirectoryGroup": { "type": "object", "properties": { "display_name": { "description": "Display Name", "type": "string", "examples": [ "Admins" ] }, "group_detail": { "description": "Complete Group Details Payload", "type": "object" }, "id": { "description": "Group ID", "type": "string", "examples": [ "dirgroup_121312434123312" ] }, "total_users": { "description": "Total Users in the Group", "type": "integer", "format": "int32", "examples": [ 10 ] }, "updated_at": { "description": "Updated At", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] } } }, "directoriesDirectoryProvider": { "type": "string", "enum": [ "OKTA", "GOOGLE", "MICROSOFT_AD", "AUTH0", "ONELOGIN", "JUMPCLOUD", "PING_IDENTITY" ] }, "directoriesDirectoryType": { "type": "string", "enum": [ "SCIM", "LDAP", "POLL" ] }, "directoriesDirectoryUser": { "type": "object", "properties": { "email": { "description": "Email", "type": "string", "examples": [ "johndoe" ] }, "emails": { "description": "Emails", "type": "array", "items": { "type": "string" } }, "family_name": { "description": "Last Name", "type": "string", "examples": [ "Doe" ] }, "given_name": { "description": "First Name", "type": "string", "examples": [ "John" ] }, "groups": { "description": "Groups", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesDirectoryGroup" } }, "id": { "description": "User ID", "type": "string", "examples": [ "diruser_121312434123312" ] }, "preferred_username": { "description": "Preferred Username", "type": "string", "examples": [ "johndoe" ] }, "updated_at": { "description": "Updated At", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] }, "user_detail": { "description": "Complete User Details Payload", "type": "object" } } }, "directoriesGetDirectoryResponse": { "type": "object", "properties": { "directory": { "description": "Detailed information about the requested directory", "$ref": "#/components/schemas/directoriesDirectory" } } }, "directoriesListDirectoriesResponse": { "type": "object", "properties": { "directories": { "description": "List of directories associated with the organization", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesDirectory" } } } }, "directoriesListDirectoryGroupsResponse": { "type": "object", "properties": { "groups": { "description": "List of directory groups retrieved from the specified directory", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesDirectoryGroup" } }, "next_page_token": { "description": "Token to retrieve the next page of results. Use this token in the 'page_token' field of the next request", "type": "string" }, "prev_page_token": { "description": "Token to retrieve the previous page of results. Use this token in the 'page_token' field of the next request", "type": "string" }, "total_size": { "description": "Total number of groups matching the request criteria, regardless of pagination", "type": "integer", "format": "int64" } } }, "directoriesListDirectoryUsersResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for pagination. Use this token in the 'page_token' field of the next request to fetch the subsequent page of users", "type": "string" }, "prev_page_token": { "description": "Token for pagination. Use this token in the 'page_token' field of the next request to fetch the prior page of users", "type": "string" }, "total_size": { "description": "Total number of users available in the directory that match the request criteria", "type": "integer", "format": "int64" }, "users": { "description": "List of directory users retrieved from the specified directory", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesDirectoryUser" } } } }, "directoriesRoleAssignment": { "type": "object", "properties": { "group_id": { "description": "group ID for the role mapping", "type": "string", "examples": [ "dirgroup_121312434123" ] }, "role_name": { "type": "string" } } }, "directoriesRoleAssignments": { "type": "object", "properties": { "assignments": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/directoriesRoleAssignment" } } } }, "directoriesSecret": { "type": "object", "properties": { "create_time": { "description": "Creation Time", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] }, "directory_id": { "description": "Directory ID", "type": "string", "examples": [ "dir_12362474900684814" ] }, "expire_time": { "description": "Expiry Time", "type": "string", "format": "date-time", "examples": [ "2025-10-01T00:00:00Z" ] }, "id": { "type": "string" }, "last_used_time": { "description": "Last Used Time", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] }, "secret_suffix": { "description": "Secret Suffix", "type": "string", "examples": [ "Nzg5" ] }, "status": { "description": "Secret Status", "$ref": "#/components/schemas/directoriesSecretStatus", "examples": [ "INACTIVE" ] } } }, "directoriesSecretStatus": { "type": "string", "enum": [ "INACTIVE" ] }, "directoriesStats": { "type": "object", "properties": { "group_updated_at": { "description": "Max time of Group Updated At for Directory", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] }, "total_groups": { "description": "Total Groups in the Directory", "type": "integer", "format": "int32", "examples": [ 10 ] }, "total_users": { "description": "Total Users in the Directory", "type": "integer", "format": "int32", "examples": [ 10 ] }, "user_updated_at": { "description": "Max time of User Updated At for Directory", "type": "string", "format": "date-time", "examples": [ "2024-10-01T00:00:00Z" ] } } }, "directoriesToggleDirectoryResponse": { "type": "object", "properties": { "enabled": { "description": "Specifies the directory's state after the toggle operation. A value of `true` indicates that the directory is enabled and actively synchronizing users and groups. A value of `false` means the directory is disabled, halting synchronization", "type": "boolean", "examples": [ true ] }, "error_message": { "description": "Contains a human-readable error message if the toggle operation encountered an issue. If the operation was successful, this field will be empty", "type": "string", "examples": [ "The directory is already enabled" ] } } }, "domainsCreateDomainResponse": { "type": "object", "properties": { "domain": { "description": "The newly created domain object with all configuration details and system-generated identifiers.", "$ref": "#/components/schemas/domainsDomain" } } }, "domainsDomain": { "type": "object", "properties": { "create_time": { "description": "Timestamp when the domain was first created.", "type": "string", "format": "date-time", "examples": [ "2025-09-01T12:14:43.100000Z" ] }, "domain": { "description": "The business domain name that was configured for allowed email domain functionality (e.g., company.com, subdomain.company.com).", "type": "string", "examples": [ "customerdomain.com" ] }, "domain_type": { "example": "ORGANIZATION_DOMAIN" }, "environment_id": { "description": "The environment ID where this domain is configured.", "type": "string", "examples": [ "env_58345499215790610" ] }, "id": { "description": "Scalekit-generated unique identifier for this domain record.", "type": "string", "examples": [ "dom_88351643129225005" ] }, "organization_id": { "description": "The organization to which the domain belongs.", "type": "string", "examples": [ "org_81667076086825451" ] }, "update_time": { "description": "Timestamp when the domain was last updated.", "type": "string", "format": "date-time", "examples": [ "2025-09-01T12:14:43.110455Z" ] }, "verification_method": { "description": "Method that determines how domain ownership is verified.\n- ADMIN: domain is marked verified without DNS validation, typically by an admin.\n- DNS: domain must be verified by adding a TXT record to your DNS configuration.\n- NOT_APPLICABLE: verification does not apply to this domain type.", "$ref": "#/components/schemas/domainsVerificationMethod", "examples": [ "ADMIN" ] }, "verification_status": { "description": "Verification status of the domain.\n- PENDING: DNS TXT record has not been validated yet.\n- VERIFIED: domain confirmed via DNS TXT record validation or admin approval.\n- AUTO_VERIFIED: domain verified automatically without DNS changes.\n- FAILED: DNS TXT record was not validated within the verification window.", "$ref": "#/components/schemas/domainsVerificationStatus", "examples": [ "AUTO_VERIFIED" ] } } }, "domainsDomainType": { "type": "string", "enum": [ "ALLOWED_EMAIL_DOMAIN", "ORGANIZATION_DOMAIN" ], "x-enum-varnames": [ "ORGANIZATION_DOMAIN", "ALLOWED_EMAIL_DOMAIN" ] }, "domainsGetDomainResponse": { "type": "object", "properties": { "domain": { "description": "The requested domain object with complete details including domain type, timestamps and configuration.", "$ref": "#/components/schemas/domainsDomain" } } }, "domainsListDomainResponse": { "type": "object", "properties": { "domains": { "description": "Array of domain objects containing all domain details including verification status and configuration.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/domainsDomain" } }, "page_number": { "description": "Current page number in the pagination sequence.", "type": "integer", "format": "int32", "examples": [ 1 ] }, "page_size": { "description": "Number of domains returned in this page.", "type": "integer", "format": "int32", "examples": [ 1 ] } } }, "domainsVerificationMethod": { "type": "string", "enum": [ "ADMIN", "DNS", "NOT_APPLICABLE" ] }, "domainsVerificationStatus": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED" ] }, "errdetailsDebugInfo": { "description": "Describes additional debugging info.", "type": "object", "properties": { "detail": { "description": "Additional debugging information provided by the server.", "type": "string" }, "stack_entries": { "description": "The stack trace entries indicating where the error occurred.", "type": "array", "items": { "type": "string" } } } }, "errdetailsErrorInfo": { "type": "object", "properties": { "debug_info": { "$ref": "#/components/schemas/errdetailsDebugInfo" }, "error_code": { "type": "string" }, "help_info": { "$ref": "#/components/schemas/errdetailsHelpInfo" }, "localized_message_info": { "$ref": "#/components/schemas/errdetailsLocalizedMessageInfo" }, "request_info": { "$ref": "#/components/schemas/errdetailsRequestInfo" }, "resource_info": { "$ref": "#/components/schemas/errdetailsResourceInfo" }, "tool_error_info": { "$ref": "#/components/schemas/errdetailsToolErrorInfo" }, "validation_error_info": { "$ref": "#/components/schemas/errdetailsValidationErrorInfo" } } }, "errdetailsHelpInfo": { "description": "HelpInfo provides documentation links attached to an error response.\nWhen present in ErrorInfo, clients should surface these links to help\ndevelopers resolve the error. For example, a missing required field error\nmay include a link to the relevant guide.", "type": "object", "properties": { "links": { "description": "One or more links relevant to resolving the error.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/HelpInfoLink" } } } }, "errdetailsLocalizedMessageInfo": { "type": "object", "properties": { "locale": { "type": "string" }, "message": { "type": "string" } } }, "errdetailsRequestInfo": { "description": "Contains metadata about the request that clients can attach when filing a bug\nor providing other forms of feedback.", "type": "object", "properties": { "request_id": { "description": "An opaque string that should only be interpreted by the service generating\nit. For example, it can be used to identify requests in the service's logs.", "type": "string" }, "serving_data": { "description": "Any data that was used to serve this request. For example, an encrypted\nstack trace that can be sent back to the service provider for debugging.", "type": "string" } } }, "errdetailsResourceInfo": { "description": "Describes the resource that is being accessed.", "type": "object", "properties": { "description": { "description": "Describes what error is encountered when accessing this resource.\nFor example, updating a cloud project may require the `writer` permission\non the developer console project.", "type": "string" }, "owner": { "type": "string" }, "required_permissions": { "description": "The required permissions needed to access the resource.", "type": "array", "items": { "type": "string" } }, "resource_name": { "type": "string" }, "user": { "type": "string" } } }, "errdetailsToolErrorInfo": { "type": "object", "properties": { "execution_id": { "type": "string" }, "tool_error_code": { "type": "string" }, "tool_error_message": { "type": "string" } } }, "errdetailsValidationErrorInfo": { "description": "Describes violations in a client request. This error type focuses on the\nsyntactic aspects of the request.", "type": "object", "properties": { "field_violations": { "description": "Describes all violations in a client request.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/ValidationErrorInfoFieldViolation" } } } }, "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 connections in `DIRECT` mode.", "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" ] }, "tool_exposure": { "description": "How the server exposes tools to agents. `DIRECT` lists every tool you map to it, for up to 25 connections. `META` gives agents five tools to search for, inspect and run the mapped tools, with no limit on connections. `DIRECT` is the default when you create a server without it.", "$ref": "#/components/schemas/mcpToolExposure", "examples": [ "DIRECT" ] }, "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" } } }, "mcpToolExposure": { "type": "string", "description": "How a Virtual MCP server exposes tools: `DIRECT` lists every mapped tool, `META` gives agents five tools to search for and run them.", "enum": [ "DIRECT", "META" ] }, "mcpUpdateMcpConfigResponse": { "type": "object", "properties": { "config": { "description": "The updated MCP configuration", "$ref": "#/components/schemas/mcpMcpConfig" } } }, "organizationsCreateOrganizationResponse": { "type": "object", "properties": { "organization": { "description": "The newly created organization containing its ID, settings, and metadata", "$ref": "#/components/schemas/organizationsOrganization" } } }, "organizationsGeneratePortalLinkResponse": { "type": "object", "properties": { "link": { "description": "Contains the generated admin portal link details. The link URL can be shared with organization administrators to set up: Single Sign-On (SSO) authentication and directory synchronization", "$ref": "#/components/schemas/organizationsLink" } } }, "organizationsGetOrganizationResponse": { "type": "object", "properties": { "organization": { "description": "The newly created organization", "$ref": "#/components/schemas/organizationsOrganization" } } }, "organizationsGetOrganizationSessionPolicyResponse": { "type": "object", "properties": { "policy": { "description": "The session policy for the organization.", "$ref": "#/components/schemas/organizationsOrganizationSessionPolicySettings" } } }, "organizationsLink": { "type": "object", "properties": { "expire_time": { "description": "Expiry time of the link. The link is valid for 1 minute.", "type": "string", "format": "date-time", "examples": [ "2024-02-06T14:48:00Z" ] }, "id": { "description": "Unique Identifier for the link", "type": "string", "examples": [ "lnk_123123123123123" ] }, "location": { "description": "Location of the link. This is the URL that can be used to access the Admin portal. The link is valid for 1 minute", "type": "string", "examples": [ "https://example.com/portal/lnk_{id}" ] } } }, "organizationsListOrganizationsResponse": { "type": "object", "properties": { "next_page_token": { "description": "Pagination token for the next page of results. Use this token to fetch the next page.", "type": "string", "examples": [ "" ] }, "organizations": { "description": "List of organization objects", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/organizationsOrganization" } }, "prev_page_token": { "description": "Pagination token for the previous page of results. Use this token to fetch the previous page.", "type": "string", "examples": [ "" ] }, "total_size": { "description": "Total number of organizations in the environment.", "type": "integer", "format": "int64", "examples": [ 30 ] } } }, "organizationsOrganization": { "type": "object", "required": [ "create_time" ], "properties": { "create_time": { "description": "Timestamp when the organization was created", "type": "string", "format": "date-time", "title": "Created Time", "examples": [ "2025-02-15T06:23:44.560000Z" ] }, "display_name": { "description": "Name of the organization. Must be between 1 and 200 characters", "type": "string", "title": "Name of the org to be used in display", "examples": [ "Megasoft" ] }, "external_id": { "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", "type": "string", "title": "External Id is useful to store a unique identifier for a given Org that. The unique Identifier can be the id of your tenant / org in your SaaSApp", "examples": [ "my_unique_id" ] }, "id": { "description": "Unique scalekit-generated identifier that uniquely references an organization", "type": "string", "title": "Id", "examples": [ "org_59615193906282635" ] }, "logo_url": { "description": "HTTPS URL of the organization's logo image. Maximum 1024 characters. Must use the https scheme.", "type": "string", "format": "uri", "maxLength": 1024, "pattern": "^https://", "examples": [ "https://cdn.example.com/acme-logo.png" ] }, "metadata": { "description": "Key value pairs extension attributes.", "type": "object", "additionalProperties": { "type": "string" } }, "region_code": { "description": "Geographic region code for the organization. Currently limited to US.", "title": "Optional regioncode", "$ref": "#/components/schemas/commonsRegionCode", "examples": [ "US" ] }, "settings": { "title": "Organization Settings", "$ref": "#/components/schemas/organizationsOrganizationSettings" }, "slug": { "description": "Slug for dynamic redirect URI resolution. A single DNS label (e.g. acme) or hostname (e.g. oauth.pstmn.io). Lowercase alphanumeric, hyphens, and dots. Max 253 chars. Unique per environment.", "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$", "examples": [ "acme" ] }, "update_time": { "description": "Timestamp when the organization was last updated", "type": "string", "format": "date-time", "title": "Updated time", "examples": [ "2025-02-15T06:23:44.560000Z" ] } } }, "organizationsOrganizationSessionPolicySettings": { "type": "object", "properties": { "absolute_session_timeout": { "description": "The absolute session timeout value. The unit is specified by absolute_session_timeout_unit. Omitted when policy_source is 'environment'.", "type": "integer", "format": "int32", "examples": [ 360 ] }, "absolute_session_timeout_unit": { "description": "Unit for absolute_session_timeout. Accepted values: 'minutes', 'hours', 'days'. Responses always return 'minutes'.", "$ref": "#/components/schemas/commonsTimeUnit", "examples": [ "minutes" ] }, "idle_session_timeout": { "description": "The idle session timeout value. The unit is specified by idle_session_timeout_unit. Omitted when idle_session_timeout_enabled is false or policy_source is 'environment'.", "type": "integer", "format": "int32", "examples": [ 84 ] }, "idle_session_timeout_enabled": { "description": "Whether idle session timeout is enabled for this organization. Omitted when policy_source is 'environment'.", "type": "boolean", "examples": [ true ] }, "idle_session_timeout_unit": { "description": "Unit for idle_session_timeout. Accepted values: 'minutes', 'hours', 'days'. Responses always return 'minutes'.", "$ref": "#/components/schemas/commonsTimeUnit", "examples": [ "minutes" ] }, "policy_source": { "description": "Policy source. 'APPLICATION' means the organization inherits the application-level session policy. 'CUSTOM' means organization-specific timeout values are active.", "$ref": "#/components/schemas/organizationsSessionPolicyType", "examples": [ "CUSTOM" ] } } }, "organizationsOrganizationSettings": { "description": "Configuration options that control organization-level features and capabilities", "type": "object", "title": "Organization Settings", "properties": { "features": { "description": "List of feature toggles that control organization capabilities such as SSO authentication and directory synchronization", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/organizationsOrganizationSettingsFeature" }, "examples": [ [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] ] } }, "examples": [ { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "dir_sync" } ] } ] }, "organizationsOrganizationSettingsFeature": { "description": "Controls the activation state of a specific organization feature", "type": "object", "title": "Organization Feature Toggle", "required": [ "name", "enabled" ], "properties": { "enabled": { "description": "Whether the feature is enabled (true) or disabled (false) for this organization", "type": "boolean", "examples": [ true ] }, "name": { "description": "Feature identifier. Supported values include: \"sso\" (Single Sign-On), \"dir_sync\" (Directory Synchronization), \"domain_verification\" (Domain Verification), \"session_policy\" (Organization-level session policy override)", "type": "string", "examples": [ "sso" ] } } }, "organizationsOrganizationUserManagementSettings": { "type": "object", "properties": { "max_allowed_users": { "description": "Maximum number of users allowed in the organization. When nil (not set), there feature is not enabled. When explicitly set to zero, it also means no limit. When set to a positive integer, it enforces the maximum user limit.", "type": "integer", "format": "int32", "examples": [ 100 ] } } }, "organizationsSessionPolicyType": { "type": "string", "enum": [ "APPLICATION", "CUSTOM" ] }, "organizationsUpdateOrganizationResponse": { "type": "object", "properties": { "organization": { "description": "Updated organization details", "$ref": "#/components/schemas/organizationsOrganization" } } }, "organizationsUpdateOrganizationSessionPolicyResponse": { "type": "object", "properties": { "policy": { "description": "The updated session policy for the organization.", "$ref": "#/components/schemas/organizationsOrganizationSessionPolicySettings" } } }, "organizationsUpsertUserManagementSettingsResponse": { "type": "object", "properties": { "settings": { "description": "The updated setting.", "$ref": "#/components/schemas/organizationsOrganizationUserManagementSettings" } } }, "passwordlessResendPasswordlessRequest": { "type": "object", "properties": { "auth_request_id": { "description": "The authentication request identifier from the original send passwordless email request. Use this to resend the Verification Code (OTP) or Magic Link to the same email address.", "type": "string", "examples": [ "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" ] } } }, "passwordlessSendPasswordlessRequest": { "type": "object", "properties": { "email": { "description": "Email address where the passwordless authentication credentials will be sent. Must be a valid email format.", "type": "string", "examples": [ "john.doe@example.com" ] }, "expires_in": { "description": "Time in seconds until the passwordless authentication expires. If not specified, defaults to 300 seconds (5 minutes)", "type": "integer", "format": "int64", "examples": [ 300 ] }, "magiclink_auth_uri": { "description": "Your application's callback URL where users will be redirected after clicking the magic link in their email. The link token will be appended as a query parameter as link_token", "type": "string", "examples": [ "https://yourapp.com/auth/passwordless/callback" ] }, "state": { "description": "Custom state parameter that will be returned unchanged in the verification response. Use this to maintain application state between the authentication request and callback, such as the intended destination after login", "type": "string", "examples": [ "d62ivasry29lso" ] }, "template": { "description": "Specifies the authentication intent for the passwordless request. Use SIGNIN for existing users or SIGNUP for new user registration. This affects the email template and user experience flow.", "$ref": "#/components/schemas/passwordlessTemplateType", "examples": [ "SIGNIN" ] }, "template_variables": { "description": "A set of key-value pairs to personalize the email template.\n\n* You may include up to 30 key-value pairs.\n* The following variable names are reserved by the system and cannot be supplied: `otp`, `expiry_time_relative`, `link`, `expire_time`, `expiry_time`.\n* Every variable referenced in your email template must be included as a key-value pair.\n\nUse these variables to insert custom information, such as a team name, URL or the user's employee ID. All variables are interpolated before the email is sent, regardless of the email provider.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "custom_variable_key": "custom_variable_value" } ] } } }, "passwordlessSendPasswordlessResponse": { "type": "object", "properties": { "auth_request_id": { "description": "Unique identifier for this passwordless authentication request. Use this ID to resend emails.", "type": "string", "readOnly": true, "examples": [ "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" ] }, "expires_at": { "description": "Unix timestamp (seconds since epoch) when the passwordless authentication will expire. After this time, the OTP or magic link will no longer be valid.", "type": "string", "format": "int64", "readOnly": true, "examples": [ 1748696575 ] }, "expires_in": { "description": "Number of seconds from now until the passwordless authentication expires. This is a convenience field calculated from the expires_at timestamp.", "type": "integer", "format": "int64", "readOnly": true, "examples": [ 300 ] }, "passwordless_type": { "description": "Type of passwordless authentication that was sent via email. OTP sends a numeric code, LINK sends a clickable magic link, and LINK_OTP provides both options for user convenience.", "$ref": "#/components/schemas/authpasswordlessPasswordlessType", "examples": [ "OTP" ] } } }, "passwordlessTemplateType": { "type": "string", "enum": [ "SIGNIN", "SIGNUP" ] }, "passwordlessVerifyPasswordLessRequest": { "type": "object", "properties": { "auth_request_id": { "description": "The authentication request identifier returned from the send passwordless email endpoint. Required when verifying OTP codes to link the verification with the original request.", "type": "string", "examples": [ "h5Y8kT5RVwaea5WEgW4n-6C-aO_-fuTUW7Vb9-Rh3AcY9qxZqQ" ] }, "code": { "description": "The Verification Code (OTP) received via email. This is typically a 6-digit numeric code that users enter manually to verify their identity.", "type": "string", "examples": [ "123456" ] }, "link_token": { "description": "The unique token from the magic link URL received via email. Extract this token when users click the magic link and are redirected to your application to later verify the user.", "type": "string", "examples": [ "afe9d61c-d80d-4020-a8ee-61765ab71cb3" ] } } }, "passwordlessVerifyPasswordLessResponse": { "type": "object", "properties": { "email": { "description": "Email address of the successfully authenticated user. This confirms which email account was verified through the passwordless flow.", "type": "string", "readOnly": true, "examples": [ "john.doe@example.com" ] }, "passwordless_type": { "description": "The type of passwordless authentication that was successfully verified, confirming which method the user completed.", "$ref": "#/components/schemas/authpasswordlessPasswordlessType", "examples": [ "OTP" ] }, "state": { "description": "The custom state parameter that was provided in the original authentication request, returned unchanged. Use this to restore your application's context after authentication.", "type": "string", "readOnly": true, "examples": [ "kdt7yiag28t341fr1" ] }, "template": { "description": "Specifies which email template to choose. For User Signin choose SIGNIN and for User Signup use SIGNUP", "$ref": "#/components/schemas/passwordlessTemplateType", "examples": [ "SIGNIN" ] } } }, "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" } } }, "rolesAddPermissionsToRoleResponse": { "type": "object", "properties": { "permissions": { "description": "List of all permissions belonging to the role after addition", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/rolesPermission" } } } }, "rolesCreateOrganizationRoleResponse": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/v1rolesRole" } } }, "rolesCreatePermissionResponse": { "type": "object", "properties": { "permission": { "$ref": "#/components/schemas/rolesPermission" } } }, "rolesCreateRoleResponse": { "type": "object", "properties": { "role": { "description": "The created role object with system-generated ID and all configuration details.", "$ref": "#/components/schemas/v1rolesRole", "examples": [ { "description": "Can edit content", "display_name": "Content Editor", "id": "role_1234abcd5678efgh", "name": "content_editor" } ] } } }, "rolesGetOrganizationRoleResponse": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/v1rolesRole" } } }, "rolesGetPermissionResponse": { "type": "object", "properties": { "permission": { "$ref": "#/components/schemas/rolesPermission" } } }, "rolesGetRoleResponse": { "type": "object", "properties": { "role": { "description": "The complete role object with all metadata, permissions, and inheritance details.", "$ref": "#/components/schemas/v1rolesRole", "examples": [ { "dependent_roles_count": 2, "display_name": "Content Editor", "id": "role_1234abcd5678efgh", "name": "content_editor", "permissions": [ { "name": "read:content" } ] } ] } } }, "rolesGetRoleUsersCountResponse": { "type": "object", "properties": { "count": { "description": "Number of users associated with the role", "type": "string", "format": "int64", "examples": [ 10 ] } } }, "rolesListDependentRolesResponse": { "type": "object", "properties": { "roles": { "description": "List of dependent roles", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/v1rolesRole" } } } }, "rolesListEffectiveRolePermissionsResponse": { "type": "object", "properties": { "permissions": { "description": "List of all effective permissions including those inherited from base roles", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/rolesPermission" } } } }, "rolesListOrganizationRolesResponse": { "type": "object", "properties": { "roles": { "description": "List of roles objects", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/v1rolesRole" } } } }, "rolesListPermissionsResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token to retrieve next page of results", "type": "string", "examples": [ "token_def456" ] }, "permissions": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/rolesPermission" } }, "prev_page_token": { "description": "Token to retrieve previous page of results", "type": "string", "examples": [ "token_def456" ] }, "total_size": { "description": "Total number of permissions available", "type": "integer", "format": "int64", "examples": [ 150 ] } } }, "rolesListRolePermissionsResponse": { "type": "object", "properties": { "permissions": { "description": "List of permissions directly assigned to the role", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/rolesPermission" } } } }, "rolesListRolesResponse": { "type": "object", "properties": { "roles": { "description": "List of all roles in the environment with their metadata and optionally their permissions.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/v1rolesRole" }, "examples": [ [ { "display_name": "Administrator", "id": "role_1234abcd5678efgh", "name": "admin" }, { "display_name": "Viewer", "id": "role_9876zyxw5432vuts", "name": "viewer" } ] ] } } }, "rolesPermission": { "type": "object", "title": "Permission Entity", "properties": { "create_time": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "string" }, "is_scalekit_permission": { "description": "Indicates whether this permission is predefined by Scalekit", "type": "boolean", "examples": [ true ] }, "name": { "type": "string" }, "update_time": { "type": "string", "format": "date-time" } } }, "rolesRolePermission": { "type": "object", "title": "RolePermissions represents a permission with role source information", "properties": { "create_time": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role_name": { "description": "Name of the role from which this permission was sourced", "type": "string", "examples": [ "admin_role" ] }, "update_time": { "type": "string", "format": "date-time" } } }, "rolesUpdateDefaultOrganizationRolesResponse": { "type": "object", "properties": { "default_member": { "description": "Updated default member role", "$ref": "#/components/schemas/v1rolesRole", "examples": [ { "description": "Role for regular members", "display_name": "Member Role", "id": "role_0987654321", "name": "member" } ] } } }, "rolesUpdateDefaultRole": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Unique name of the role", "type": "string", "examples": [ "creator" ] } } }, "rolesUpdateDefaultRolesRequest": { "type": "object", "properties": { "default_creator": { "description": "Default creator role (deprecated - use default_creator_role field instead)", "$ref": "#/components/schemas/rolesUpdateDefaultRole", "examples": [ { "description": "Role for creating resources", "display_name": "Creator Role", "id": "role_1234567890", "name": "creator" } ] }, "default_creator_role": { "description": "Name of the role to set as the default creator role. This role will be automatically assigned to users who create new resources in the environment. Must be a valid role name that exists in the environment.", "type": "string", "examples": [ "creator" ] }, "default_member": { "description": "Default member role (deprecated - use default_member_role field instead)", "$ref": "#/components/schemas/rolesUpdateDefaultRole", "examples": [ { "description": "Role for regular members", "display_name": "Member Role", "id": "role_0987654321", "name": "member" } ] }, "default_member_role": { "description": "Name of the role to set as the default member role. This role will be automatically assigned to new users when they join the environment. Must be a valid role name that exists in the environment.", "type": "string", "examples": [ "member" ] } } }, "rolesUpdateDefaultRolesResponse": { "type": "object", "properties": { "default_creator": { "description": "The role that is now set as the default creator role for the environment. Contains complete role information including permissions and metadata.", "$ref": "#/components/schemas/v1rolesRole", "examples": [ { "description": "Role for creating resources", "display_name": "Creator Role", "id": "role_1234567890", "name": "creator" } ] }, "default_member": { "description": "The role that is now set as the default member role for the environment. Contains complete role information including permissions and metadata.", "$ref": "#/components/schemas/v1rolesRole", "examples": [ { "description": "Role for regular members", "display_name": "Member Role", "id": "role_0987654321", "name": "member" } ] } } }, "rolesUpdateOrganizationRoleResponse": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/v1rolesRole" } } }, "rolesUpdatePermissionResponse": { "type": "object", "properties": { "permission": { "$ref": "#/components/schemas/rolesPermission" } } }, "rolesUpdateRoleResponse": { "type": "object", "properties": { "role": { "description": "The updated role object with all current configuration details.", "$ref": "#/components/schemas/v1rolesRole", "examples": [ { "description": "Can edit and approve content", "display_name": "Senior Editor", "id": "role_1234abcd5678efgh", "name": "content_editor" } ] } } }, "sessionsAuthenticatedClients": { "description": "AuthenticatedClients represents an authenticated client in a session along with its organization context.", "type": "object", "properties": { "client_id": { "description": "Unique identifier of the authenticated client application.", "type": "string", "examples": [ "skc_1234567890" ] }, "organization_id": { "description": "Active or last active Organization ID associated with the authenticated client.", "type": "string", "examples": [ "org_1234567890" ] } } }, "sessionsDeviceDetails": { "type": "object", "properties": { "browser": { "description": "Browser name and family extracted from the user agent. Examples: Chrome, Safari, Firefox, Edge, Mobile Safari.", "type": "string", "examples": [ "Chrome" ] }, "browser_version": { "description": "Version of the browser application. Represents the specific release version of the browser being used.", "type": "string", "examples": [ "120.0.0.0" ] }, "device_type": { "description": "Categorized device type classification. Possible values: 'desktop' (traditional computers), 'mobile' (smartphones and small tablets), 'tablet' (large tablets), 'other'. Useful for displaying session information by device category.", "type": "string", "examples": [ "desktop" ] }, "ip": { "description": "IP address of the device that initiated the session. This is the public-facing IP address used to connect to the application. Useful for security audits and geographic distribution analysis.", "type": "string", "examples": [ "192.0.2.1" ] }, "location": { "description": "Geographic location information derived from IP address geolocation. Includes country, region, city, and coordinates. Note: Based on IP location data and may not represent the user's exact physical location.", "$ref": "#/components/schemas/v1sessionsLocation" }, "os": { "description": "Operating system name extracted from the user agent and device headers. Examples: macOS, Windows, Linux, iOS, Android.", "type": "string", "examples": [ "macOS" ] }, "os_version": { "description": "Version of the operating system. Represents the specific OS release the device is running.", "type": "string", "examples": [ "14.2" ] }, "user_agent": { "description": "Complete HTTP User-Agent header string from the client request. Contains browser type, version, and operating system information. Used for detailed device fingerprinting and user agent analysis.", "type": "string", "examples": [ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" ] } } }, "sessionsRevokeAllUserSessionsResponse": { "type": "object", "properties": { "revoked_sessions": { "description": "List of all sessions that were revoked, including detailed information for each revoked session with IDs, timestamps, and device details.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/sessionsRevokedSessionDetails" } }, "total_revoked": { "description": "Total count of active sessions that were revoked. Useful for confirmation and audit logging.", "type": "integer", "format": "int64", "examples": [ 5 ] } } }, "sessionsRevokeSessionResponse": { "type": "object", "properties": { "revoked_session": { "description": "Details of the revoked session including session ID, user ID, creation and revocation timestamps, and final device information.", "$ref": "#/components/schemas/sessionsRevokedSessionDetails" } } }, "sessionsRevokedSessionDetails": { "type": "object", "properties": { "absolute_expires_at": { "description": "The absolute expiration timestamp that was configured for this session before revocation. Represents the hard deadline regardless of activity.", "type": "string", "format": "date-time", "examples": [ "2025-01-22T10:30:00Z" ] }, "created_at": { "description": "Timestamp indicating when the session was originally created before revocation.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T10:30:00Z" ] }, "expired_at": { "description": "Timestamp when the session was actually terminated. Set to the revocation time when the session is revoked.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T12:00:00Z" ] }, "idle_expires_at": { "description": "The idle expiration timestamp that was configured for this session before revocation. Represents when the session would have expired due to inactivity.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T11:30:00Z" ] }, "last_active_at": { "description": "Timestamp of the last recorded user activity in this session before revocation. Helps identify inactive sessions that were revoked.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T10:55:30Z" ] }, "logout_at": { "description": "Timestamp when the user explicitly logged out (if applicable). Null if the session was revoked without prior logout.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T14:00:00Z" ] }, "session_id": { "description": "Unique identifier for the revoked session. System-generated read-only field.", "type": "string", "examples": [ "ses_1234567890123456" ] }, "status": { "description": "Status of the session after revocation. Always 'revoked' since only active sessions can be revoked. Sessions that were already expired or logged out are not included in the revocation response.", "type": "string", "examples": [ "revoked" ] }, "updated_at": { "description": "Timestamp indicating when the session was last modified before revocation.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T10:45:00Z" ] }, "user_id": { "description": "Unique identifier for the user who owned this session.", "type": "string", "examples": [ "usr_1234567890123456" ] } } }, "sessionsSessionDetails": { "type": "object", "properties": { "absolute_expires_at": { "description": "Hard expiration timestamp for the session regardless of user activity. The session will be forcibly terminated at this time. This represents the maximum session lifetime from creation.", "type": "string", "format": "date-time", "examples": [ "2025-01-22T10:30:00Z" ] }, "authenticated_clients": { "description": "Details of the authenticated clients for this session: client ID and organization context.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/sessionsAuthenticatedClients" } }, "authenticated_organizations": { "description": "List of organization IDs that have been authenticated for this user within the current session. Contains all organizations where the user has successfully completed SSO or authentication.", "type": "array", "items": { "type": "string" }, "examples": [ [ "org_123", "org_456" ] ] }, "created_at": { "description": "Timestamp indicating when the session was created. This is set once at session creation and remains constant throughout the session lifetime.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T10:30:00Z" ] }, "device": { "description": "Complete device metadata associated with this session including browser, operating system, device type, and geographic location based on IP address.", "$ref": "#/components/schemas/sessionsDeviceDetails" }, "expired_at": { "description": "Timestamp when the session was terminated. Null if the session is still active. Set when the session expires due to reaching idle_expires_at or absolute_expires_at timeout, or when administratively revoked. Not set for user-initiated logout (see logout_at instead).", "type": "string", "format": "date-time", "examples": [ "2025-01-15T12:00:00Z" ] }, "idle_expires_at": { "description": "Projected expiration timestamp if the session remains idle without user activity. This timestamp is recalculated with each user activity. Session will be automatically terminated at this time if no activity occurs.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T11:30:00Z" ] }, "last_active_at": { "description": "Timestamp of the most recent user activity detected in this session. Updated on each API request or user interaction. Used to determine if a session has exceeded the idle timeout threshold.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T10:55:30Z" ] }, "logout_at": { "description": "Timestamp when the user explicitly logged out from the session. Null if the user has not logged out. When set, indicates the session ended due to explicit user logout rather than timeout.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T14:00:00Z" ] }, "organization_id": { "description": "Organization ID for the user's most recently active organization within this session. This represents the primary organization context for the current session.", "type": "string", "examples": [ "org_1234567890123456" ] }, "session_id": { "description": "Unique identifier for the session. System-generated read-only field used to reference this session.", "type": "string", "examples": [ "ses_1234567890123456" ] }, "status": { "description": "Current operational status of the session. Possible values: 'active' (session is valid and requests are allowed), 'expired' (session terminated due to idle or absolute timeout), 'revoked' (session was administratively revoked), 'logout' (user explicitly logged out). Use this to determine if the session can be used for new requests.", "type": "string", "examples": [ "active" ] }, "updated_at": { "description": "Timestamp indicating when the session was last updated. Updated whenever session state changes such as organization context changes or metadata updates.", "type": "string", "format": "date-time", "examples": [ "2025-01-15T10:45:00Z" ] }, "user_id": { "description": "Unique identifier for the user who owns and is authenticated within this session.", "type": "string", "examples": [ "usr_1234567890123456" ] } } }, "sessionsUserSessionDetails": { "type": "object", "properties": { "next_page_token": { "description": "Pagination token for retrieving the next page of results. Empty string if there are no more pages (you have reached the final page of results).", "type": "string", "examples": [ "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAic2VzXzEyMzQ1In0=" ] }, "prev_page_token": { "description": "Pagination token for retrieving the previous page of results. Empty string for the first page. Use this to navigate backward through result pages.", "type": "string", "examples": [ "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInNlc183OTAxIn0=" ] }, "sessions": { "description": "Array of session objects for the requested user. May contain fewer entries than the requested page_size when reaching the final page of results.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/sessionsSessionDetails" } }, "total_size": { "description": "Total number of sessions matching the applied filter criteria, regardless of pagination. This represents the complete result set size before pagination is applied.", "type": "integer", "format": "int64", "examples": [ 42 ] } } }, "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" ] } } }, "usersCreateMembershipResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/usersUser" } } }, "usersCreateUser": { "type": "object", "properties": { "email": { "description": "Primary email address for the user. Must be unique across the environment and valid per RFC 5322.", "type": "string", "examples": [ "user@example.com" ] }, "external_id": { "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", "type": "string", "examples": [ "ext_12345a67b89c" ] }, "membership": { "description": "List of organization memberships. Automatically populated based on group assignments.", "$ref": "#/components/schemas/v1usersCreateMembership" }, "metadata": { "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "location": "nyc-office" } ] }, "user_profile": { "description": "User's personal information including name, address, and other profile attributes.", "$ref": "#/components/schemas/usersCreateUserProfile" } } }, "usersCreateUserAndMembershipResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/usersUser" } } }, "usersCreateUserProfile": { "type": "object", "properties": { "custom_attributes": { "description": "Custom attributes for extended user profile data. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "security_clearance": "level2" } ] }, "family_name": { "description": "User's family name. Maximum 255 characters.", "type": "string", "examples": [ "Doe" ] }, "gender": { "description": "User's gender identity.", "type": "string", "examples": [ "male" ] }, "given_name": { "description": "User's given name. Maximum 255 characters.", "type": "string", "examples": [ "John" ] }, "groups": { "description": "List of group names the user belongs to. Each group name must be 1-250 characters", "type": "array", "items": { "type": "string" }, "examples": [ [ "engineering", "managers" ] ] }, "locale": { "description": "User's localization preference in BCP-47 format. Defaults to organization settings.", "type": "string", "examples": [ "en-US" ] }, "metadata": { "description": "System-managed key-value pairs for internal tracking. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "account_status": "active", "signup_source": "mobile_app" } ] }, "name": { "description": "Full name in display format. Typically combines first_name and last_name.", "type": "string", "examples": [ "John Michael Doe" ] }, "phone_number": { "description": "Phone number in E.164 international format. Required for SMS-based authentication.", "type": "string", "examples": [ "+14155552671" ] }, "picture": { "description": "URL to the user's profile picture or avatar.", "type": "string", "examples": [ "https://example.com/avatar.jpg" ] }, "preferred_username": { "description": "User's preferred username for display purposes.", "type": "string", "examples": [ "John Michael Doe" ] } } }, "usersGetUserResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/usersUser" } } }, "usersInvite": { "type": "object", "properties": { "created_at": { "description": "Timestamp when the invite was originally created.", "type": "string", "format": "date-time", "examples": [ "2025-07-10T08:00:00Z" ] }, "expires_at": { "description": "The time at which the invite expires.", "type": "string", "format": "date-time", "examples": [ "2025-12-31T23:59:59Z" ] }, "inviter_email": { "description": "Identifier of the user or system that initiated the invite.", "type": "string", "examples": [ "admin@example.com" ] }, "organization_id": { "description": "The organization to which the invite belongs.", "type": "string", "examples": [ "org_987654321" ] }, "resent_at": { "description": "Timestamp when the invite was last resent, if applicable.", "type": "string", "format": "date-time", "examples": [ "2025-07-15T09:30:00Z" ] }, "resent_count": { "description": "Number of times the invite has been resent.", "type": "integer", "format": "int32", "examples": [ 2 ] }, "status": { "description": "Current status of the invite (e.g., pending, accepted, expired, revoked).", "type": "string", "examples": [ "pending_invite" ] }, "user_id": { "description": "User ID to whom the invite is sent. May be empty if the user has not signed up yet.", "type": "string", "examples": [ "usr_123456" ] } } }, "usersListOrganizationUsersResponse": { "type": "object", "properties": { "next_page_token": { "description": "Opaque token for retrieving the next page of results. Empty if there are no more pages.", "type": "string", "examples": [ "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" ] }, "prev_page_token": { "description": "Opaque token for retrieving the previous page of results. Empty for the first page.", "type": "string", "examples": [ "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" ] }, "total_size": { "description": "Total number of users matching the request criteria, regardless of pagination.", "type": "integer", "format": "int64", "examples": [ 1042 ] }, "users": { "description": "List of user objects for the current page. May contain fewer entries than requested page_size.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/usersUser" } } } }, "usersListUserPermissionsResponse": { "type": "object", "properties": { "permissions": { "description": "List of permissions the user has access to", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/usersPermission" } } } }, "usersListUserRolesResponse": { "type": "object", "properties": { "roles": { "description": "List of roles assigned to the user", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/commonsRole" } } } }, "usersListUsersResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for retrieving the next page of results. Empty if there are no more pages.", "type": "string", "examples": [ "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" ] }, "prev_page_token": { "description": "Token for retrieving the previous page of results. Empty if this is the first page.", "type": "string", "examples": [ "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" ] }, "total_size": { "description": "Total number of users matching the request criteria, regardless of pagination.", "type": "integer", "format": "int64", "examples": [ 1042 ] }, "users": { "description": "List of users.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/usersUser" } } } }, "usersPermission": { "type": "object", "properties": { "description": { "description": "Description of what the permission allows", "type": "string", "examples": [ "Allows creating new user accounts" ] }, "id": { "description": "Unique identifier for the permission", "type": "string", "readOnly": true, "examples": [ "perm_1234abcd5678efgh" ] }, "name": { "description": "Unique name identifier for the permission", "type": "string", "examples": [ "users:create" ] } } }, "usersResendInviteResponse": { "type": "object", "properties": { "invite": { "description": "Updated invitation object containing the resent invitation details, including new expiration time and incremented resend counter.", "$ref": "#/components/schemas/usersInvite", "examples": [ { "expires_at": "2025-12-31T23:59:59Z", "organization_id": "org_123", "resent_count": 2, "status": "pending_invite", "user_id": "usr_456" } ] } } }, "usersSearchOrganizationUsersResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for retrieving the next page of results. Empty if there are no more pages.", "type": "string", "examples": [ "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" ] }, "prev_page_token": { "description": "Token for retrieving the previous page of results. Empty if this is the first page.", "type": "string", "examples": [ "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" ] }, "total_size": { "description": "Total number of users matching the request criteria, regardless of pagination.", "type": "integer", "format": "int64", "examples": [ 1042 ] }, "users": { "description": "List of matching users.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/usersUser" } } } }, "usersSearchUsersResponse": { "type": "object", "properties": { "next_page_token": { "description": "Token for retrieving the next page of results. Empty if there are no more pages.", "type": "string", "examples": [ "eyJwYWdlIjogMiwgImxhc3RfaWQiOiAidXNyXzEyMzQ1In0=" ] }, "prev_page_token": { "description": "Token for retrieving the previous page of results. Empty if this is the first page.", "type": "string", "examples": [ "eyJwYWdlIjogMCwgImZpcnN0X2lkIjogInVzcl85ODc2NSJ9" ] }, "total_size": { "description": "Total number of users matching the request criteria, regardless of pagination.", "type": "integer", "format": "int64", "examples": [ 1042 ] }, "users": { "description": "List of matching users.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/usersUser" } } } }, "usersUpdateMembershipResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/usersUser" } } }, "usersUpdateUserProfile": { "type": "object", "properties": { "custom_attributes": { "description": "Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. 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": [ { "department": "engineering", "security_clearance": "level2" } ] }, "family_name": { "description": "Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed.", "type": "string", "examples": [ "Doe" ] }, "first_name": { "description": "[DEPRECATED] Use given_name instead. User's given name. Maximum 200 characters.", "type": "string", "examples": [ "John" ] }, "gender": { "description": "Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies.", "type": "string", "examples": [ "male" ] }, "given_name": { "description": "Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed.", "type": "string", "examples": [ "John" ] }, "groups": { "description": "Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user.", "type": "array", "items": { "type": "string" }, "examples": [ [ "engineering", "managers" ] ] }, "last_name": { "description": "[DEPRECATED] Use family_name instead. User's family name. Maximum 200 characters.", "type": "string", "examples": [ "Doe" ] }, "locale": { "description": "Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`.", "type": "string", "examples": [ "en-US" ] }, "metadata": { "description": "Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. 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": [ { "account_status": "active", "signup_source": "mobile_app" } ] }, "name": { "description": "Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed.", "type": "string", "examples": [ "John Doe" ] }, "phone_number": { "description": "Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is required when enabling SMS authentication features.", "type": "string", "examples": [ "+14155552671" ] }, "picture": { "description": "Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters.", "type": "string", "examples": [ "https://example.com/avatar.jpg" ] }, "preferred_username": { "description": "Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed.", "type": "string", "examples": [ "John Michael Doe" ] } } }, "usersUpdateUserResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/usersUser" } } }, "usersUser": { "type": "object", "properties": { "create_time": { "description": "Timestamp when the user account was initially created. Automatically set by the server.", "type": "string", "format": "date-time", "readOnly": true }, "email": { "description": "Primary email address for the user. Must be unique across the environment and valid per RFC 5322.", "type": "string", "examples": [ "user@example.com" ] }, "external_id": { "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", "type": "string", "examples": [ "ext_12345a67b89c" ] }, "id": { "description": "Unique system-generated identifier for the user. Immutable once created.", "type": "string", "examples": [ "usr_1234abcd5678efgh" ] }, "last_login_time": { "description": "Timestamp of the user's most recent successful authentication. Updated automatically.", "type": "string", "format": "date-time", "readOnly": true }, "memberships": { "description": "List of organization memberships. Automatically populated based on group assignments.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/commonsOrganizationMembership" } }, "metadata": { "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "location": "nyc-office" } ] }, "update_time": { "description": "Timestamp of the last modification to the user account. Automatically updated by the server.", "type": "string", "format": "date-time", "readOnly": true }, "user_profile": { "description": "User's personal information including name, address, and other profile attributes.", "$ref": "#/components/schemas/commonsUserProfile" } } }, "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" ] } } ] } } }, "v1domainsCreateDomain": { "type": "object", "properties": { "domain": { "description": "The domain name to be configured. Must be a valid business domain you control. Public and disposable domains (gmail.com, outlook.com, etc.) are automatically blocked for security.", "type": "string", "examples": [ "customerdomain.com" ] }, "domain_type": { "description": "The domain type.\n- ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the organization in the organization switcher during sign-in/sign-up.\n- ORGANIZATION_DOMAIN: SSO discovery domain used to route users to the correct SSO provider and enforce SSO.\n", "$ref": "#/components/schemas/domainsDomainType", "examples": [ "ORGANIZATION_DOMAIN" ] } } }, "v1organizationsCreateOrganization": { "type": "object", "required": [ "display_name" ], "properties": { "display_name": { "description": "Name of the organization. Must be between 1 and 200 characters.", "type": "string", "examples": [ "Megasoft Inc" ] }, "external_id": { "description": "Your application's unique identifier for this organization, used to link Scalekit with your system.", "type": "string", "examples": [ "my_unique_id" ] }, "logo_url": { "description": "HTTPS URL of the organization's logo image. Maximum 1024 characters. Must use the https scheme.", "type": "string", "format": "uri", "maxLength": 1024, "pattern": "^https://", "examples": [ "https://cdn.example.com/acme-logo.png" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "slug": { "description": "Slug for dynamic redirect URI resolution. A single DNS label (e.g. acme) or hostname (e.g. oauth.pstmn.io). Lowercase alphanumeric, hyphens, and dots. Max 253 chars. Unique per environment.", "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$", "examples": [ "acme" ] } } }, "v1organizationsUpdateOrganization": { "description": "For update messages ensure the indexes are same as the base model itself.", "type": "object", "properties": { "display_name": { "description": "Name of the organization to display in the UI. Must be between 1 and 200 characters", "type": "string", "examples": [ "Acme Corporation" ] }, "external_id": { "description": "Your application's unique identifier for this organization, used to link Scalekit with your system", "type": "string", "examples": [ "tenant_12345" ] }, "logo_url": { "description": "HTTPS URL of the organization's logo image. Maximum 1024 characters. Must use the https scheme.", "type": "string", "format": "uri", "maxLength": 1024, "pattern": "^https://", "examples": [ "https://cdn.example.com/acme-logo.png" ] }, "metadata": { "description": "Custom key-value pairs to store with the organization. Keys must be 3-25 characters, values must be 1-256 characters. Maximum 10 pairs allowed.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "industry": "technology" } ] }, "slug": { "description": "Slug for dynamic redirect URI resolution. A single DNS label (e.g. acme) or hostname (e.g. oauth.pstmn.io). Lowercase alphanumeric, hyphens, and dots. Max 253 chars. Send empty string to clear.", "type": "string", "maxLength": 253, "pattern": "^$|^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$", "examples": [ "acme" ] } } }, "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" ] } } }, "v1rolesCreateOrganizationRole": { "type": "object", "properties": { "description": { "description": "Description of the organization's role", "type": "string", "examples": [ "Organization Viewer Role will be used only for viewing the objects" ] }, "display_name": { "description": "Display name of the organization's role", "type": "string", "examples": [ "Organization Viewer Role" ] }, "extends": { "description": "Base role name for hierarchical roles", "type": "string", "examples": [ "admin_role" ] }, "name": { "description": "Unique name of the organization's role", "type": "string", "examples": [ "org_viewer_role" ] }, "permissions": { "description": "List of permission names to assign to this role. Permissions must exist in the current environment.", "type": "array", "items": { "type": "string" }, "examples": [ [ "read:users", "write:documents" ] ] } } }, "v1rolesCreatePermission": { "type": "object", "properties": { "description": { "description": "Description of the permission", "type": "string", "examples": [ "Allows user to read documents from the system" ] }, "name": { "description": "Unique name/ID of the permission. Must be 1–64 characters using only letters, numbers, underscores (_), and colons (:).", "type": "string", "examples": [ "read:documents" ] } } }, "v1rolesCreateRole": { "type": "object", "properties": { "description": { "description": "Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.", "type": "string", "examples": [ "Can create, edit, and publish content but cannot delete content or manage user accounts" ] }, "display_name": { "description": "Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.", "type": "string", "examples": [ "Content Editor" ] }, "extends": { "description": "Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.", "type": "string", "examples": [ "viewer" ] }, "name": { "description": "Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation.", "type": "string", "examples": [ "content_editor" ] }, "permissions": { "description": "List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role.", "type": "array", "items": { "type": "string" }, "examples": [ [ "read:content", "write:content", "publish:content" ] ] } } }, "v1rolesRole": { "type": "object", "properties": { "default_creator": { "description": "Indicates if this role is the default creator role for new organizations.", "type": "boolean", "examples": [ true ] }, "default_member": { "description": "Indicates if this role is the default member role for new users.", "type": "boolean", "examples": [ true ] }, "dependent_roles_count": { "description": "Number of roles that extend from this role (dependent roles count). Read-only field.", "type": "integer", "format": "int32", "examples": [ 3 ] }, "description": { "description": "Detailed description of the role's purpose and capabilities. Maximum 2000 characters.", "type": "string", "examples": [ "Can create, edit, and publish content but cannot delete or manage users" ] }, "display_name": { "description": "Human-readable display name for the role. Used in user interfaces and reports.", "type": "string", "examples": [ "Content Editor" ] }, "extends": { "description": "Name of the base role that this role extends. Enables hierarchical role inheritance.", "type": "string", "examples": [ "admin_role" ] }, "id": { "description": "Unique system-generated identifier for the role. Immutable once created.", "type": "string", "readOnly": true, "examples": [ "role_1234abcd5678efgh" ] }, "is_org_role": { "description": "Indicates if this role is an organization role.", "type": "boolean", "examples": [ true ] }, "name": { "description": "Unique name identifier for the role. Must be alphanumeric with underscores, 1-100 characters.", "type": "string", "examples": [ "content_editor" ] }, "permissions": { "description": "List of permissions with role source information. Only included when 'include' parameter is specified in the request.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/rolesRolePermission" }, "examples": [ [ { "description": "Read Content", "name": "read:content", "role_name": "admin_role" }, { "description": "Write Content", "name": "write:content", "role_name": "editor_role" } ] ] } } }, "v1rolesUpdateRole": { "type": "object", "properties": { "description": { "description": "Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.", "type": "string", "examples": [ "Can create, edit, publish, and approve content. Cannot delete content or manage user accounts." ] }, "display_name": { "description": "Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.", "type": "string", "examples": [ "Senior Content Editor" ] }, "extends": { "description": "Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.", "type": "string", "examples": [ "content_editor" ] }, "permissions": { "description": "List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role.", "type": "array", "items": { "type": "string" }, "examples": [ [ "read:content", "write:content", "publish:content", "approve:content" ] ] } } }, "v1sessionsLocation": { "type": "object", "properties": { "city": { "description": "City name where the session originated based on IP geolocation. Approximate location derived from IP address.", "type": "string", "examples": [ "San Francisco" ] }, "latitude": { "description": "Latitude coordinate of the estimated location. Decimal format (e.g., '37.7749'). Note: Represents IP geolocation center and may not be precise.", "type": "string", "examples": [ "37.7749" ] }, "longitude": { "description": "Longitude coordinate of the estimated location. Decimal format (e.g., '-122.4194'). Note: Represents IP geolocation center and may not be precise.", "type": "string", "examples": [ "-122.4194" ] }, "region": { "description": "Geographic region name derived from IP geolocation. Represents the country-level location (e.g., 'United States', 'France').", "type": "string", "examples": [ "United States" ] }, "region_subdivision": { "description": "Regional subdivision code or name (e.g., state abbreviation for US, province for Canada). Two-letter ISO format when applicable.", "type": "string", "examples": [ "CA" ] } } }, "v1usersCreateMembership": { "type": "object", "properties": { "inviter_email": { "description": "Email address of the user who invited this member. Must be a valid email address.", "type": "string", "examples": [ "john.doe@example.com" ] }, "metadata": { "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "location": "nyc-office" } ] }, "roles": { "description": "Role to assign to the user within the organization", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/commonsRole" }, "examples": [ [ { "name": "admin" } ] ] } } }, "v1usersUpdateMembership": { "type": "object", "properties": { "metadata": { "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "location": "nyc-office" } ] }, "roles": { "description": "Role to assign to the user within the organization", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/commonsRole" }, "examples": [ [ { "name": "admin" } ] ] } } }, "v1usersUpdateUser": { "type": "object", "properties": { "external_id": { "description": "Your application's unique identifier for this user, used to link Scalekit with your system.", "type": "string", "examples": [ "ext_12345a67b89c" ] }, "metadata": { "description": "Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "department": "engineering", "location": "nyc-office" } ] }, "user_profile": { "description": "User's personal information including name, address, and other profile attributes.", "$ref": "#/components/schemas/usersUpdateUserProfile" } } }, "webauthnAllAcceptedCredentialsOptions": { "type": "object", "properties": { "all_accepted_credential_ids": { "description": "List of credential IDs the user can authenticate with", "type": "array", "items": { "type": "string" } }, "rp_id": { "description": "Relying Party ID for credential operations", "type": "string", "examples": [ "example.com" ] }, "user_id": { "description": "User ID for credential verification", "type": "string", "examples": [ "user_xyz789" ] } } }, "webauthnDeleteCredentialResponse": { "type": "object", "properties": { "success": { "description": "Whether the credential was successfully deleted", "type": "boolean", "examples": [ true ] }, "unknown_credential_options": { "description": "Options for handling unknown credentials in client applications", "$ref": "#/components/schemas/webauthnUnknownCredentialOptions" } } }, "webauthnListCredentialsResponse": { "type": "object", "properties": { "all_accepted_credentials_options": { "description": "Options including RP ID and all accepted credential IDs for authentication", "$ref": "#/components/schemas/webauthnAllAcceptedCredentialsOptions" }, "credentials": { "description": "All passkeys registered for the user", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/webauthnWebAuthnCredential" } } } }, "webauthnUnknownCredentialOptions": { "type": "object", "properties": { "credential_id": { "description": "The deleted credential ID", "type": "string", "examples": [ "cred_abc123" ] }, "rp_id": { "description": "The RP ID for this credential", "type": "string", "examples": [ "example.com" ] } } }, "webauthnUpdateCredentialResponse": { "type": "object", "properties": { "credential": { "description": "The updated credential with new display name", "$ref": "#/components/schemas/webauthnWebAuthnCredential" } } }, "webauthnWebAuthnCredential": { "type": "object", "properties": { "attestation_type": { "description": "Type of attestation: \"none\", \"indirect\", or \"direct\"", "type": "string", "examples": [ "direct" ] }, "authenticator": { "description": "Authenticator information including model and name", "$ref": "#/components/schemas/WebAuthnCredentialAuthenticator" }, "authenticator_flags": { "description": "Flags indicating authenticator capabilities", "$ref": "#/components/schemas/WebAuthnCredentialAuthenticatorFlags" }, "client_info": { "description": "Geographic and network information from registration", "$ref": "#/components/schemas/WebAuthnCredentialClientInfo" }, "created_at": { "description": "Timestamp when the credential was created", "type": "string", "format": "date-time", "examples": [ "2025-02-15T06:23:44.560000Z" ] }, "credential_id": { "description": "The actual credential ID bytes from the authenticator", "type": "string", "contentEncoding": "base64" }, "display_name": { "description": "Optional user-friendly name for this passkey", "type": "string", "examples": [ "My Yubikey" ] }, "id": { "description": "Credential unique identifier", "type": "string", "examples": [ "cred_abc123" ] }, "transports": { "description": "Supported transports for this credential", "type": "array", "items": { "type": "string" } }, "updated_at": { "description": "Timestamp of last update", "type": "string", "format": "date-time", "examples": [ "2025-02-15T06:23:44.560000Z" ] }, "user_agent": { "description": "Browser and device information from registration", "$ref": "#/components/schemas/WebAuthnCredentialUserAgent" }, "user_id": { "description": "User ID this credential belongs to", "type": "string", "examples": [ "user_xyz789" ] } } }, "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": "john@acmecorp.com", "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" } } }, "OrganizationDomainEventData": { "type": "object", "description": "Domain payload shared by organization domain lifecycle webhook events. Field names differ from the Domain resource in the REST API. Every key is sent, including empty strings and null values.", "required": [ "id", "domain", "domain_type", "organization_id", "txt_record_key", "txt_record_secret", "verification_status", "verification_method", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^dom_", "example": "dom_1234567890", "description": "Unique identifier for the domain (prefixed with \"dom_\")" }, "domain": { "type": "string", "example": "acmecorp.com", "description": "The domain name" }, "domain_type": { "type": "string", "enum": [ "ORGANIZATION_DOMAIN", "ALLOWED_EMAIL_DOMAIN" ], "example": "ORGANIZATION_DOMAIN", "description": "ORGANIZATION_DOMAIN for SSO/SCIM routing domains; ALLOWED_EMAIL_DOMAIN for auto-join email domains" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "Organization that owns the domain" }, "txt_record_key": { "type": "string", "example": "scalekit-domain-verification", "description": "DNS TXT record host used for ownership verification" }, "txt_record_secret": { "type": "string", "example": "", "description": "DNS TXT record value Scalekit expects during verification. Treat as sensitive: do not log, display in client UIs, or store in shared channels. Present on domain lifecycle events including after verification or deletion." }, "verification_status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED", "AUTO_VERIFIED" ], "example": "PENDING", "description": "Verification status of the domain" }, "verification_method": { "type": [ "string", "null" ], "enum": [ "ADMIN", "DNS", "NOT_APPLICABLE", null ], "example": "DNS", "description": "How ownership is verified: DNS (TXT record), ADMIN (dashboard or API without DNS), or NOT_APPLICABLE (allowed email domains). Null when no method is set." }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-01-15T11:00:00.123456789Z", "description": "When the domain status last changed" } } }, "OrganizationDomainCreatedEvent": { "type": "object", "description": "Payload delivered for the organization.domain_created webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "example": "evt_4567890123", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "organization.domain_created" ], "example": "organization.domain_created" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2024-01-15T11:00:00.123456789Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_1234567890", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "The organization ID" }, "data": { "$ref": "#/components/schemas/OrganizationDomainEventData" } } }, "OrganizationDomainDeletedEvent": { "type": "object", "description": "Payload delivered for the organization.domain_deleted webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "example": "evt_4567890456", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "organization.domain_deleted" ], "example": "organization.domain_deleted" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2024-01-16T09:30:00.123456789Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_1234567890", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "The organization ID" }, "data": { "$ref": "#/components/schemas/OrganizationDomainEventData" } } }, "OrganizationDomainDnsVerificationSuccessEvent": { "type": "object", "description": "Payload delivered for the organization.domain_dns_verification_success webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "example": "evt_4567890789", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "organization.domain_dns_verification_success" ], "example": "organization.domain_dns_verification_success" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2024-01-15T12:15:00.123456789Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_1234567890", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "The organization ID" }, "data": { "$ref": "#/components/schemas/OrganizationDomainEventData", "example": { "id": "dom_1234567890", "domain": "acmecorp.com", "domain_type": "ORGANIZATION_DOMAIN", "organization_id": "org_1234567890", "txt_record_key": "scalekit-domain-verification", "txt_record_secret": "", "verification_status": "VERIFIED", "verification_method": "DNS", "updated_at": "2024-01-15T12:15:00.123456789Z" } } } }, "OrganizationDomainDnsVerificationFailedEvent": { "type": "object", "description": "Payload delivered for the organization.domain_dns_verification_failed webhook event.", "required": [ "spec_version", "id", "type", "occurred_at", "environment_id", "data" ], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "example": "evt_4567891012", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "organization.domain_dns_verification_failed" ], "example": "organization.domain_dns_verification_failed" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2024-01-16T11:00:00.123456789Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_1234567890", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "The organization ID" }, "data": { "$ref": "#/components/schemas/OrganizationDomainEventData", "example": { "id": "dom_1234567890", "domain": "acmecorp.com", "domain_type": "ORGANIZATION_DOMAIN", "organization_id": "org_1234567890", "txt_record_key": "scalekit-domain-verification", "txt_record_secret": "", "verification_status": "FAILED", "verification_method": "DNS", "updated_at": "2024-01-16T11:00:00.123456789Z" } } } }, "OrganizationEventData": { "type": "object", "description": "Organization payload for organization.created, organization.updated and organization.deleted. On organization.updated it is the organization after the change.", "required": [ "id", "display_name", "external_id", "region_code", "create_time", "update_time", "metadata", "settings", "deleted_at" ], "properties": { "id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "Scalekit organization identifier" }, "display_name": { "type": "string", "example": "AcmeCorp", "description": "Organization display name" }, "external_id": { "type": [ "string", "null" ], "example": "org_external_123", "description": "Your system's unique ID for this organization. Null when not set." }, "slug": { "type": "string", "example": "acmecorp", "description": "Organization slug. Sent only when set." }, "region_code": { "type": "string", "example": "US", "description": "Region code for the organization. Empty string when not set." }, "create_time": { "type": "string", "format": "date-time", "example": "2025-12-09T09:25:02.02Z", "description": "When the organization was created" }, "update_time": { "type": "string", "format": "date-time", "example": "2025-12-09T09:25:02.025330364Z", "description": "When the organization was last updated" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the organization was deleted. Null except on organization.deleted." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Organization metadata map. Null when not set." }, "settings": { "type": [ "object", "null" ], "description": "Organization settings. Null when the organization has none. Each key is sent only when set.", "properties": { "features": { "type": "array", "description": "Features enabled or disabled for this organization, such as sso and dir_sync", "items": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" } } } }, "roles": { "type": "array", "description": "Roles defined for this organization", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string" }, "description": { "type": "string" }, "default": { "type": "boolean" }, "default_creator": { "type": "boolean" }, "default_member": { "type": "boolean" }, "extends": { "type": "string" } } } }, "default_roles": { "type": "object", "description": "Default role assignment for this organization", "properties": { "default_member": { "type": "string" } } } } } } }, "OrganizationCreatedEvent": { "type": "object", "description": "Payload delivered for the organization.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_", "example": "evt_1234567890", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "organization.created" ], "example": "organization.created" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2024-01-15T10:30:00.123456789Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_1234567890", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890", "description": "The organization ID" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "Organization" ], "example": "Organization" }, "data": { "$ref": "#/components/schemas/OrganizationEventData" } } }, "DirectoryUserEventData": { "type": "object", "description": "Directory user payload for organization.directory.user_* webhook events. The first seven fields are always sent. roles is computed by Scalekit and sent on every user event when your environment has roles. The others are sent only when the directory provider supplies them. The user_deleted event carries the last known user record.", "required": [ "id", "organization_id", "active", "preferred_username", "dp_id", "email", "groups" ], "properties": { "id": { "type": "string", "pattern": "^diruser_", "example": "diruser_53891546960887884", "description": "Unique identifier for the directory user" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_53879494091473415", "description": "Organization that owns the directory" }, "active": { "type": "boolean", "example": true, "description": "Whether the user is active in the directory provider. False on a user_deleted event sent because the user was deactivated." }, "preferred_username": { "type": "string", "example": "john.doe@acmecorp.com", "description": "The user's userName from the directory provider. Empty string when not set." }, "dp_id": { "type": "string", "example": "00u1a2b3c4d5e6f7g8h9", "description": "The user's externalId from the directory provider. Empty string when not set." }, "email": { "type": [ "string", "null" ], "format": "email", "example": "john.doe@acmecorp.com", "description": "Primary email address. Null when the provider marks no email as primary." }, "groups": { "type": [ "array", "null" ], "description": "Directory groups the user belongs to. Null when the user is in no groups.", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dirgroup_", "example": "dirgroup_53891546960887900" }, "name": { "type": "string", "example": "Engineering" } } } }, "name": { "type": "string", "example": "John Doe", "description": "Display name" }, "given_name": { "type": "string", "example": "John", "description": "Given (first) name" }, "family_name": { "type": "string", "example": "Doe", "description": "Family (last) name" }, "nickname": { "type": "string", "example": "Johnny", "description": "Nickname" }, "picture": { "type": "string", "example": "https://example.com/john.jpg", "description": "Profile picture URL" }, "phone_number": { "type": "string", "example": "+1-555-0100", "description": "Work phone number" }, "address": { "type": "object", "description": "The user's SCIM address of type work. state comes from the SCIM region attribute.", "properties": { "street_address": { "type": "string" }, "locality": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "formatted": { "type": "string" }, "country": { "type": "string" } } }, "profile": { "type": "string", "description": "Profile URL" }, "locale": { "type": "string", "example": "en-US", "description": "Locale" }, "zoneinfo": { "type": "string", "example": "America/New_York", "description": "Time zone" }, "language": { "type": "string", "example": "en", "description": "Preferred language" }, "title": { "type": "string", "example": "Software Engineer", "description": "Job title" }, "user_type": { "type": "string", "example": "Employee", "description": "User type" }, "employee_id": { "type": "string", "example": "E1234", "description": "Employee number from the enterprise extension" }, "cost_center": { "type": "string", "description": "Cost center from the enterprise extension" }, "organization": { "type": "string", "description": "Organization from the enterprise extension" }, "division": { "type": "string", "description": "Division from the enterprise extension" }, "department": { "type": "string", "example": "Engineering", "description": "Department from the enterprise extension" }, "manager": { "type": "object", "description": "The user's manager, when the manager is also in the directory", "properties": { "id": { "type": "string", "pattern": "^diruser_" }, "email": { "type": "string" }, "user_name": { "type": "string" } } }, "roles": { "type": "array", "description": "Scalekit roles assigned to the user through group-based role assignment. Computed by Scalekit, not sent by the provider. Present on every user event when your environment has roles; an empty array when no role applies.", "items": { "type": "object", "properties": { "role_name": { "type": "string", "example": "billing_admin" } } } }, "dp_roles": { "type": [ "array", "null" ], "description": "Roles as sent by the directory provider. Null when the provider sends an empty roles list.", "items": { "$ref": "#/components/schemas/DirectoryUserProviderValue" } }, "entitlements": { "type": [ "array", "null" ], "description": "Entitlements as sent by the directory provider. Null when the provider sends an empty entitlements list.", "items": { "$ref": "#/components/schemas/DirectoryUserProviderValue" } }, "custom_attributes": { "type": "object", "additionalProperties": true, "description": "Custom attributes you mapped for this directory, plus home_phone_number and mobile_phone_number when the provider sends them" }, "raw_attributes": { "type": "object", "additionalProperties": true, "description": "The SCIM user resource as received from the directory provider" } } }, "DirectoryUserProviderValue": { "type": "object", "properties": { "display": { "type": "string" }, "primary": { "type": "boolean" }, "type": { "type": "string" }, "value": { "type": "string" } } }, "DirectoryUserCreatedEvent": { "type": "object", "description": "Payload delivered for the organization.directory.user_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_", "example": "evt_53891546994442316", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")" }, "type": { "type": "string", "description": "The event type", "enum": [ "organization.directory.user_created" ], "example": "organization.directory.user_created" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2025-01-06T18:44:25.153954Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_53814739859406915", "description": "The environment ID where the event occurred" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_53879494091473415", "description": "The organization ID" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "DirectoryUser" ], "example": "DirectoryUser" }, "data": { "$ref": "#/components/schemas/DirectoryUserEventData" } } }, "WebhookUser": { "type": "object", "description": "The user the event is about.", "required": [ "id", "email", "create_time", "update_time", "last_login_time", "metadata", "user_profile" ], "properties": { "id": { "type": "string", "pattern": "^usr_" }, "email": { "type": "string", "format": "email" }, "external_id": { "type": "string", "description": "Your ID for the user. Sent only when the user has one." }, "create_time": { "type": "string", "format": "date-time" }, "update_time": { "type": "string", "format": "date-time" }, "last_login_time": { "type": [ "string", "null" ], "format": "date-time", "description": "When the user last logged in. null if the user has never logged in." }, "metadata": { "type": "object", "additionalProperties": true }, "user_profile": { "$ref": "#/components/schemas/WebhookUserProfile" } } }, "WebhookUserProfile": { "type": "object", "description": "The user's profile. Empty values are sent as empty strings, not left out.", "required": [ "id", "name", "given_name", "family_name", "preferred_username", "email_verified", "phone_number", "phone_number_verified", "picture", "gender", "locale", "metadata", "custom_attributes", "groups", "external_identities" ], "properties": { "id": { "type": "string", "pattern": "^usp_" }, "name": { "type": "string" }, "given_name": { "type": "string" }, "family_name": { "type": "string" }, "preferred_username": { "type": "string" }, "email_verified": { "type": "boolean" }, "phone_number": { "type": "string" }, "phone_number_verified": { "type": "boolean" }, "picture": { "type": "string" }, "gender": { "type": "string" }, "locale": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "custom_attributes": { "type": [ "object", "null" ], "additionalProperties": true }, "groups": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "null when the user is in no groups" }, "external_identities": { "type": [ "array", "null" ], "description": "The identity provider accounts the user has signed in with. null when there are none.", "items": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^conn_" }, "connection_type": { "type": "string", "example": "OAUTH" }, "connection_provider": { "type": "string", "example": "GOOGLE" }, "connection_user_id": { "type": "string" }, "is_social": { "type": "boolean" }, "created_time": { "type": "string", "format": "date-time" }, "last_login_time": { "type": [ "string", "null" ], "format": "date-time" }, "last_synced_time": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "WebhookUserSession": { "type": "object", "description": "The session the user logged in or out of.", "required": [ "session_id", "user_id", "organization_id", "authenticated_organizations", "status", "created_at", "updated_at", "last_active_at", "absolute_expires_at", "idle_expires_at", "expired_at", "logout_at", "device" ], "properties": { "session_id": { "type": "string", "pattern": "^ses_" }, "user_id": { "type": "string", "pattern": "^usr_" }, "organization_id": { "type": "string", "pattern": "^org_", "description": "The organization the session is active in" }, "authenticated_organizations": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "ACTIVE", "LOGOUT", "EXPIRED", "REVOKED" ], "description": "ACTIVE on user.login. LOGOUT or EXPIRED on user.logout." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_active_at": { "type": "string", "format": "date-time" }, "absolute_expires_at": { "type": "string", "format": "date-time" }, "idle_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set only while the session is active and has an idle timeout" }, "expired_at": { "type": [ "string", "null" ], "format": "date-time" }, "logout_at": { "type": [ "string", "null" ], "format": "date-time" }, "device": { "type": [ "object", "null" ], "properties": { "user_agent": { "type": "string" }, "os": { "type": "string" }, "os_version": { "type": "string" }, "browser": { "type": "string" }, "browser_version": { "type": "string" }, "device_type": { "type": "string" }, "ip": { "type": "string" }, "location": { "type": [ "object", "null" ], "properties": { "region": { "type": "string" }, "region_subdivision": { "type": "string" }, "city": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" } } } } }, "authorized_clients": { "type": "array", "description": "Sent only when the session has authorized clients", "items": { "type": "object", "properties": { "client_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] } } } } } }, "OrgMembershipEventData": { "type": "object", "description": "data for user.signup, user.organization_invitation and the user.organization_membership_* events: the user and the organization. It doesn't include the membership's roles or status; fetch the membership if you need them.", "required": [ "organization", "user" ], "properties": { "organization": { "$ref": "#/components/schemas/OrganizationEventData" }, "user": { "$ref": "#/components/schemas/WebhookUser" } } }, "UserAuthEventData": { "type": "object", "description": "data for user.login and user.logout: the user and the session.", "required": [ "user", "user_session" ], "properties": { "user": { "$ref": "#/components/schemas/WebhookUser" }, "user_session": { "$ref": "#/components/schemas/WebhookUserSession" } } }, "DirectoryEventData": { "type": "object", "description": "Directory payload for organization.directory_created, organization.directory_enabled, organization.directory_disabled and organization.directory_deleted. Only directory_enabled also sends enabled and updated_at.", "required": [ "id", "organization_id", "directory_type", "provider" ], "properties": { "id": { "type": "string", "pattern": "^dir_", "example": "dir_55135622825771522", "description": "Directory identifier" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_55135410258444802", "description": "Organization that owns the directory" }, "directory_type": { "type": "string", "example": "SCIM", "description": "How the directory syncs, such as SCIM" }, "provider": { "type": "string", "example": "OKTA", "description": "Directory provider" }, "enabled": { "type": "boolean", "example": true, "description": "Always true. Sent on directory_enabled only." }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-01-15T08:55:22.792993454Z", "description": "When the directory was last updated. Sent on directory_enabled only." } } }, "DirectoryGroupEventData": { "type": "object", "description": "Directory group payload for organization.directory.group_* events. Every key is sent; dp_id and raw_attributes can be null.", "required": [ "id", "organization_id", "directory_id", "display_name", "dp_id", "raw_attributes" ], "properties": { "id": { "type": "string", "pattern": "^dirgroup_", "example": "dirgroup_40072007005503806", "description": "Directory group identifier" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_39802449573184223", "description": "Organization that owns the directory" }, "directory_id": { "type": "string", "pattern": "^dir_", "example": "dir_39802485862301855", "description": "Directory the group belongs to" }, "display_name": { "type": "string", "example": "Engineering", "description": "Group display name" }, "dp_id": { "type": [ "string", "null" ], "example": "7c66a173-79c6-4270-ac78-8f35a8121e0a", "description": "The group's externalId from the directory provider. Null when the provider doesn't send one." }, "raw_attributes": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The SCIM group resource as received from the directory provider" } } }, "ConnectionEventData": { "type": "object", "description": "SSO connection payload for organization.sso_* webhook events. Every key is always sent.", "required": [ "id", "organization_id", "connection_type", "provider", "enabled", "status" ], "properties": { "id": { "type": "string", "pattern": "^conn_", "example": "conn_94567862424830277", "description": "Connection identifier" }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_83544995172188677", "description": "Organization that owns the connection" }, "connection_type": { "type": "string", "example": "OIDC", "description": "Connection protocol, such as OIDC or SAML" }, "provider": { "type": "string", "example": "OKTA", "description": "Identity provider" }, "enabled": { "type": "boolean", "example": true, "description": "Whether the connection is enabled. True on sso_enabled; false on sso_disabled; usually false on sso_created. On sso_deleted, it is the connection's state when it was deleted: deleting an organization deletes its connections whether or not they are enabled, so sso_deleted can carry true." }, "status": { "type": "string", "enum": [ "DRAFT", "IN_PROGRESS", "COMPLETED" ], "example": "COMPLETED", "description": "The connection's last stored configuration status. COMPLETED once it is fully configured. A connection deleted before setup finished is still DRAFT or IN_PROGRESS on sso_deleted." } } }, "RoleEventData": { "type": "object", "description": "Role payload for role.* webhook events.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Role identifier" }, "name": { "type": "string", "description": "Role name" }, "display_name": { "type": "string", "description": "Human-readable role name" }, "description": { "type": "string", "description": "Role description" }, "extends": { "type": "string", "description": "Parent role this role extends, if any" } } }, "PermissionEventData": { "type": "object", "description": "Permission payload for permission.* webhook events.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Permission identifier" }, "name": { "type": "string", "description": "Permission name" }, "description": { "type": "string", "description": "Permission description" } } }, "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": "john@acmecorp.com", "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" } } }, "OrganizationUpdatedEvent": { "type": "object", "description": "Payload delivered for the organization.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": [ "organization.updated" ], "example": "organization.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": [ "Organization" ], "example": "Organization" }, "data": { "$ref": "#/components/schemas/OrganizationEventData" } } }, "OrganizationDeletedEvent": { "type": "object", "description": "Payload delivered for the organization.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": [ "organization.deleted" ], "example": "organization.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": [ "Organization" ], "example": "Organization" }, "data": { "$ref": "#/components/schemas/OrganizationEventData" } } }, "UserSignupEvent": { "type": "object", "description": "Payload delivered for the user.signup 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": [ "user.signup" ], "example": "user.signup" }, "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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "OrgMembershipEvent" ], "example": "OrgMembershipEvent" }, "data": { "$ref": "#/components/schemas/OrgMembershipEventData" } } }, "UserLoginEvent": { "type": "object", "description": "Payload delivered for the user.login 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": [ "user.login" ], "example": "user.login" }, "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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "UserLoginEvent" ], "example": "UserLoginEvent" }, "data": { "$ref": "#/components/schemas/UserAuthEventData" } } }, "UserLogoutEvent": { "type": "object", "description": "Payload delivered for the user.logout 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": [ "user.logout" ], "example": "user.logout" }, "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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "UserLogoutEvent" ], "example": "UserLogoutEvent" }, "data": { "$ref": "#/components/schemas/UserAuthEventData" } } }, "UserOrganizationInvitationEvent": { "type": "object", "description": "Payload delivered for the user.organization_invitation 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": [ "user.organization_invitation" ], "example": "user.organization_invitation" }, "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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "OrgMembershipEvent" ], "example": "OrgMembershipEvent" }, "data": { "$ref": "#/components/schemas/OrgMembershipEventData" } } }, "UserOrganizationMembershipCreatedEvent": { "type": "object", "description": "Payload delivered for the user.organization_membership_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": [ "user.organization_membership_created" ], "example": "user.organization_membership_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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "OrgMembershipEvent" ], "example": "OrgMembershipEvent" }, "data": { "$ref": "#/components/schemas/OrgMembershipEventData" } } }, "UserOrganizationMembershipDeletedEvent": { "type": "object", "description": "Payload delivered for the user.organization_membership_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": [ "user.organization_membership_deleted" ], "example": "user.organization_membership_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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "OrgMembershipEvent" ], "example": "OrgMembershipEvent" }, "data": { "$ref": "#/components/schemas/OrgMembershipEventData" } } }, "UserOrganizationMembershipUpdatedEvent": { "type": "object", "description": "Payload delivered for the user.organization_membership_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": [ "user.organization_membership_updated" ], "example": "user.organization_membership_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" }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "OrgMembershipEvent" ], "example": "OrgMembershipEvent" }, "data": { "$ref": "#/components/schemas/OrgMembershipEventData" } } }, "OrganizationDirectoryEnabledEvent": { "type": "object", "description": "Payload delivered for the organization.directory_enabled 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": [ "organization.directory_enabled" ], "example": "organization.directory_enabled" }, "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": [ "Directory" ], "example": "Directory" }, "data": { "$ref": "#/components/schemas/DirectoryEventData" } } }, "OrganizationDirectoryCreatedEvent": { "type": "object", "description": "Payload delivered for the organization.directory_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": [ "organization.directory_created" ], "example": "organization.directory_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": [ "Directory" ], "example": "Directory" }, "data": { "$ref": "#/components/schemas/DirectoryEventData" } } }, "OrganizationDirectoryDeletedEvent": { "type": "object", "description": "Payload delivered for the organization.directory_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": [ "organization.directory_deleted" ], "example": "organization.directory_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": [ "Directory" ], "example": "Directory" }, "data": { "$ref": "#/components/schemas/DirectoryEventData" } } }, "OrganizationDirectoryDisabledEvent": { "type": "object", "description": "Payload delivered for the organization.directory_disabled 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": [ "organization.directory_disabled" ], "example": "organization.directory_disabled" }, "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": [ "Directory" ], "example": "Directory" }, "data": { "$ref": "#/components/schemas/DirectoryEventData" } } }, "DirectoryUserUpdatedEvent": { "type": "object", "description": "Payload delivered for the organization.directory.user_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": [ "organization.directory.user_updated" ], "example": "organization.directory.user_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": [ "DirectoryUser" ], "example": "DirectoryUser" }, "data": { "$ref": "#/components/schemas/DirectoryUserEventData" } } }, "DirectoryUserDeletedEvent": { "type": "object", "description": "Payload delivered for the organization.directory.user_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": [ "organization.directory.user_deleted" ], "example": "organization.directory.user_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": [ "DirectoryUser" ], "example": "DirectoryUser" }, "data": { "$ref": "#/components/schemas/DirectoryUserEventData" } } }, "DirectoryGroupCreatedEvent": { "type": "object", "description": "Payload delivered for the organization.directory.group_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": [ "organization.directory.group_created" ], "example": "organization.directory.group_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": [ "DirectoryGroup" ], "example": "DirectoryGroup" }, "data": { "$ref": "#/components/schemas/DirectoryGroupEventData" } } }, "DirectoryGroupUpdatedEvent": { "type": "object", "description": "Payload delivered for the organization.directory.group_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": [ "organization.directory.group_updated" ], "example": "organization.directory.group_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": [ "DirectoryGroup" ], "example": "DirectoryGroup" }, "data": { "$ref": "#/components/schemas/DirectoryGroupEventData" } } }, "DirectoryGroupDeletedEvent": { "type": "object", "description": "Payload delivered for the organization.directory.group_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": [ "organization.directory.group_deleted" ], "example": "organization.directory.group_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": [ "DirectoryGroup" ], "example": "DirectoryGroup" }, "data": { "$ref": "#/components/schemas/DirectoryGroupEventData" } } }, "OrganizationSsoCreatedEvent": { "type": "object", "description": "Payload delivered for the organization.sso_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": [ "organization.sso_created" ], "example": "organization.sso_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": [ "Connection" ], "example": "Connection" }, "data": { "$ref": "#/components/schemas/ConnectionEventData" } } }, "OrganizationSsoEnabledEvent": { "type": "object", "description": "Payload delivered for the organization.sso_enabled 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": [ "organization.sso_enabled" ], "example": "organization.sso_enabled" }, "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": [ "Connection" ], "example": "Connection" }, "data": { "$ref": "#/components/schemas/ConnectionEventData" } } }, "OrganizationSsoDisabledEvent": { "type": "object", "description": "Payload delivered for the organization.sso_disabled 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": [ "organization.sso_disabled" ], "example": "organization.sso_disabled" }, "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": [ "Connection" ], "example": "Connection" }, "data": { "$ref": "#/components/schemas/ConnectionEventData" } } }, "OrganizationSsoDeletedEvent": { "type": "object", "description": "Payload delivered for the organization.sso_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": [ "organization.sso_deleted" ], "example": "organization.sso_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": [ "Connection" ], "example": "Connection" }, "data": { "$ref": "#/components/schemas/ConnectionEventData" } } }, "RoleCreatedEvent": { "type": "object", "description": "Payload delivered for the role.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": [ "role.created" ], "example": "role.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": [ "Role" ], "example": "Role" }, "data": { "$ref": "#/components/schemas/RoleEventData" } } }, "RoleUpdatedEvent": { "type": "object", "description": "Payload delivered for the role.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": [ "role.updated" ], "example": "role.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": [ "Role" ], "example": "Role" }, "data": { "$ref": "#/components/schemas/RoleEventData" } } }, "RoleDeletedEvent": { "type": "object", "description": "Payload delivered for the role.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": [ "role.deleted" ], "example": "role.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": [ "Role" ], "example": "Role" }, "data": { "$ref": "#/components/schemas/RoleEventData" } } }, "PermissionCreatedEvent": { "type": "object", "description": "Payload delivered for the permission.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": [ "permission.created" ], "example": "permission.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": [ "Permission" ], "example": "Permission" }, "data": { "$ref": "#/components/schemas/PermissionEventData" } } }, "PermissionUpdatedEvent": { "type": "object", "description": "Payload delivered for the permission.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": [ "permission.updated" ], "example": "permission.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": [ "Permission" ], "example": "Permission" }, "data": { "$ref": "#/components/schemas/PermissionEventData" } } }, "PermissionDeletedEvent": { "type": "object", "description": "Payload delivered for the permission.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": [ "permission.deleted" ], "example": "permission.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": [ "Permission" ], "example": "Permission" }, "data": { "$ref": "#/components/schemas/PermissionEventData" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } }, "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", "display_name" ], "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", "example": "OAuth tokens fetched", "description": "Human-readable name for the event type" } } }, "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" } } }, "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" } } }, "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", "display_name" ], "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", "example": "OAuth authentication successful", "description": "Human-readable name for the event type" } } }, "TriggerServiceBatchCreateTriggerSubscriptionsBody": { "type": "object", "required": [ "trigger_name" ], "properties": { "config": { "description": "Filter values applied to every account in the batch, keyed by the trigger's config_fields keys. Each account gets its own subscription with these values, so subscribing the same accounts again with different values adds subscriptions rather than replacing these. Invalid values refuse the whole request.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "channel": "C0123456789" } ] }, "connected_account_ids": { "description": "Connected accounts to subscribe, at most 100 — one page of the account picker — with no repeats. Which to send depends on the trigger's delivery_scope, from ListAvailableTriggers. For an ACCOUNT-scoped trigger, list at least one account; an empty list refuses the whole request with a 400. For a CONNECTION-scoped trigger, send an empty list: the trigger is subscribed once, on the connection itself, and results holds exactly one result, with an empty connected_account_id. Naming accounts for a connection-scoped trigger refuses each of them (REFUSED), since that trigger is not subscribed per account.", "type": "array", "items": { "type": "string" }, "examples": [ [ "ca_123456789012345", "ca_123456789012346" ] ] }, "interval_seconds": { "description": "Polling interval in seconds, for a polled trigger only, applied to every account in the batch. Omit it to use the trigger's default_interval_seconds. A value below the trigger's min_interval_seconds, or any value for a webhook trigger, refuses the whole request. A large batch of polled subscriptions shares the environment's polling budget, so the subscriptions can run slower than requested; effective_interval_seconds on each subscription shows the interval it runs at.", "type": "integer", "format": "int32", "examples": [ 300 ] }, "trigger_name": { "description": "Name of the trigger to subscribe to, as returned in the name field of ListAvailableTriggers. Up to 128 characters.", "type": "string", "examples": [ "slack_message_posted" ] } } }, "TriggerServiceBatchDeleteTriggerSubscriptionsBody": { "description": "Which subscriptions to delete: subscription_ids, or trigger_name with connected_account_ids.\n\nSend exactly one selector; any other combination is refused with 400. trigger_name alone, which\nwould name every subscription to a trigger, is deliberately not a selector: to delete those, page\nListTriggerSubscriptions and send the IDs.", "type": "object", "properties": { "connected_account_ids": { "description": "With trigger_name, the other selector: connected account IDs (`ca_`) whose subscriptions to trigger_name to delete, at most 100, with no repeats. One account can hold several subscriptions to one trigger, one per filter; each is deleted and gets its own result. Results are grouped by account in the order sent and, within an account, ordered by ascending subscription ID. An account with no matching subscription gets one NOT_FOUND result with an empty subscription_id. A connection-scoped subscription names no account, so it is never matched here: delete it by subscription_ids.", "type": "array", "items": { "type": "string" }, "examples": [ [ "ca_123456789012345", "ca_123456789012346" ] ] }, "subscription_ids": { "description": "Trigger subscription IDs (`trgs_`) to delete, at most 100, with no repeats. One of the two selectors: send either this, or trigger_name with connected_account_ids, never both. Results come back one per ID, in the order sent. Works for account-scoped and connection-scoped subscriptions alike.", "type": "array", "items": { "type": "string" }, "examples": [ [ "trgs_28128748834787841", "trgs_28128748834787842" ] ] }, "trigger_name": { "description": "With connected_account_ids, the other selector: deletes every subscription the listed accounts hold to this trigger on this connection, whatever its filter. Must be sent together with connected_account_ids; sent alone it is refused, so no request can delete every subscription to a trigger. Not checked against the trigger catalogue: a name no subscription uses gives NOT_FOUND for every account. At most 128 characters.", "type": "string", "examples": [ "slack_message_posted" ] } } }, "TriggerServiceConfirmTriggerSigningSecretRotationBody": { "type": "object", "properties": { "signing_secret_rotation_id": { "description": "The rotation to confirm: the signing_secret_rotation_id from the latest SetTriggerSigningSecret or GetTriggerIngressEndpoint response. Required while a rotation is in progress; a missing or non-matching value is then refused with 400, rather than confirming a rotation you did not look at. Ignored when no rotation is in progress.", "type": "string", "format": "int64", "examples": [ 3 ] } } }, "TriggerServiceCreateTriggerSubscriptionBody": { "type": "object", "required": [ "trigger_name" ], "properties": { "config": { "description": "Filter values for the subscription, keyed by the trigger's config_fields keys, spelled exactly as returned. Every required field must be set. An unknown key, or a value longer than 512 characters, is refused. Subscribing again with different values creates another subscription; subscribing again with identical values returns 409.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "channel": "C0123456789" } ] }, "connected_account_id": { "description": "Connected account to subscribe on, for an account-scoped trigger. Omit it for a connection-scoped trigger — the trigger is then subscribed on the connection itself and no account is named. Whether omitting it is valid depends on the trigger's own delivery_scope.", "type": "string", "examples": [ "ca_123456789012345" ] }, "interval_seconds": { "description": "Polling interval in seconds, for a polled trigger only. Omit it to use the trigger's default_interval_seconds. A value below the trigger's min_interval_seconds is refused, naming the minimum, rather than rounded up. Setting it for a webhook trigger is refused. The subscription can run slower than requested when the environment's polling budget is shared across many polled subscriptions; effective_interval_seconds on the response shows the interval it runs at.", "type": "integer", "format": "int32", "examples": [ 300 ] }, "trigger_name": { "description": "Name of the trigger to subscribe to, as returned in the name field of ListAvailableTriggers. Up to 128 characters.", "type": "string", "examples": [ "slack_message_posted" ] } } }, "TriggerServiceGenerateTriggerSigningSecretBody": { "type": "object" }, "TriggerServiceRecoverTriggerDeliveriesBody": { "description": "The endpoint and the window to recover failed deliveries for.\n\nThe window must not start or end in the future, must end after it starts, and must span at most\n14 days; a window that breaks a rule is refused with a 400 that names the rule.", "type": "object", "required": [ "since" ], "properties": { "since": { "description": "Start of the window, inclusive: events with a failed attempt to this endpoint at or after this instant are recovered. Must not be in the future, and must be at most 14 days before `until`, or before now when `until` is omitted.", "type": "string", "format": "date-time", "examples": [ "2026-10-08T00:00:00Z" ] }, "until": { "description": "End of the window, exclusive. Omit it to recover up to now. Must be after `since`, must not be in the future, and must be at most 14 days after `since`.", "type": "string", "format": "date-time", "examples": [ "2026-10-09T00:00:00Z" ] } } }, "TriggerServiceSetTriggerSigningSecretBody": { "type": "object", "required": [ "signing_secret" ], "properties": { "signing_secret": { "description": "The secret the provider signs its events with, copied from the provider's app configuration. For Slack this is the Signing Secret under Basic Information, not an API token. Between 8 and 4096 characters. For Gong, the RSA public key shown by 'Show public key'. Never returned by any endpoint and never written to a log.", "type": "string" } } }, "protobufEmpty": { "description": "service Foo {\n rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);\n }", "type": "object", "title": "A generic empty message that you can re-use to avoid defining duplicated\nempty messages in your APIs. A typical example is to use it as the request\nor the response type of an API method. For instance:" }, "triggersAccountHealth": { "description": "Whether a connected account can receive triggers at all.\n\nWorked out from the account's current state on every read.", "type": "object", "properties": { "action": { "description": "The single action that resolves this state, so a client renders one button rather than inventing its own mapping. Unspecified when there is nothing to do.", "$ref": "#/components/schemas/triggersAccountHealthAction", "examples": [ "RECONNECT" ] }, "blocks_tool_calls": { "description": "Whether the account's credential itself is unusable, so tool calls made with it fail too. True only for NEEDS_REAUTHENTICATION. False for AWAITING_CONFIRMATION and WRONG_APP: the credential still works and tool calls still succeed, so an agent should keep using the account; only trigger events cannot reach it.", "type": "boolean", "examples": [ false ] }, "reason": { "description": "Why the account is in this state. Empty when the state is READY.", "type": "string", "examples": [ "This account was disconnected." ] }, "remedy": { "description": "What to do about it. Empty when the state is READY.", "type": "string", "examples": [ "Connect the account again to resume triggers." ] }, "state": { "description": "READY — the account can receive triggers. AWAITING_CONFIRMATION — connected and working, but Scalekit has not confirmed which provider workspace or user it belongs to, so inbound events cannot be routed to it. WRONG_APP — authorized under a different OAuth app than the connection now uses. DISCONNECTED — the account was disconnected. NEEDS_REAUTHENTICATION — the credential itself is unusable, because it has expired or the account has not finished connecting.", "$ref": "#/components/schemas/triggersAccountHealthState", "examples": [ "AWAITING_CONFIRMATION" ] } } }, "triggersAccountHealthAction": { "description": "The single action that resolves an account's health state.\n\n - RECONNECT: Have the account's user connect the account again.\n - COMPLETE_SETUP: Have the account's user finish the connection flow the\naccount started.", "type": "string", "enum": [ "RECONNECT", "COMPLETE_SETUP" ] }, "triggersAccountHealthState": { "description": "A connected account's own state, evaluated for what the trigger in question routes by: a webhook\ntrigger needs the provider workspace captured, and an account-scoped webhook trigger the provider\nuser too.\n\n - READY: The account can receive triggers.\n - AWAITING_CONFIRMATION: Connected and working, but Scalekit has not confirmed\nwhich provider workspace or user it belongs to, so inbound events cannot be routed to it.\n - WRONG_APP: Authorized under a different OAuth app than the connection now\nuses.\n - DISCONNECTED: The account was disconnected.\n - NEEDS_REAUTHENTICATION: The credential itself is unusable: it has expired,\nor the account has not finished connecting.", "type": "string", "enum": [ "READY", "AWAITING_CONFIRMATION", "WRONG_APP", "DISCONNECTED", "NEEDS_REAUTHENTICATION" ] }, "triggersAvailableTrigger": { "description": "One trigger, as it applies to one connection.", "type": "object", "properties": { "available": { "description": "Whether this trigger can run on this connection. False does not mean the trigger is unsupported by the provider — it means something about THIS connection prevents it, and reason and remedy say what.", "type": "boolean" }, "config_fields": { "description": "Values a subscription can set in its config map to narrow which events it receives. A config key not listed here is refused.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersConfigField" } }, "default_interval_seconds": { "description": "Polling interval, in seconds, a subscription uses when it does not set interval_seconds. Zero for a webhook trigger.", "type": "integer", "format": "int32", "examples": [ 300 ] }, "delivery_scope": { "description": "Whether this trigger delivers one event per connected account or one event for the whole connection, whatever accounts exist on it. Decides how the trigger is subscribed: an account-scoped trigger is subscribed on one connected account, a connection-scoped one on the connection itself, naming no account.", "$ref": "#/components/schemas/triggersTriggerDeliveryScope", "examples": [ "ACCOUNT" ] }, "description": { "description": "What event the trigger reports.", "type": "string", "examples": [ "Fires when a new message is posted in a channel." ] }, "display_name": { "description": "Human-readable name of the trigger.", "type": "string", "examples": [ "Message posted" ] }, "min_interval_seconds": { "description": "Shortest polling interval, in seconds, a subscription to this trigger may request. A lower interval_seconds is refused rather than rounded up. Zero for a webhook trigger, which has no interval.", "type": "integer", "format": "int32", "examples": [ 60 ] }, "mode": { "description": "How the trigger detects events. WEBHOOK - the provider sends each event to the connection's webhook URL, so the connection needs a webhook URL registered with the provider. POLL - Scalekit checks the provider on an interval, so a subscription can set interval_seconds.", "$ref": "#/components/schemas/triggersTriggerMode", "examples": [ "WEBHOOK" ] }, "name": { "description": "Unique name of the trigger within its provider. Pass it as trigger_name when listing eligible accounts or creating a subscription.", "type": "string", "examples": [ "slack_message_posted" ] }, "platform_credentials": { "description": "Whether this trigger works on a connection that uses Scalekit's shared provider app. UNSUPPORTED means the connection needs the customer's own provider app before this trigger can run; combine it with connection_uses_shared_app on the list response to decide whether to ask for one. UNSPECIFIED when the trigger declares a value this server does not recognise.", "$ref": "#/components/schemas/triggersTriggerPlatformCredentials", "examples": [ "UNSUPPORTED" ] }, "provider": { "description": "The provider the trigger belongs to, the same as the connection's provider.", "type": "string", "examples": [ "slack" ] }, "provides_bearer_secret": { "description": "Whether Scalekit generates this trigger's signing secret (GenerateTriggerSigningSecret) rather than the customer copying one from the provider's console. True only for providers that send no signature of their own. Always false for a polled trigger.", "type": "boolean", "examples": [ false ] }, "reason": { "description": "Why the trigger is unavailable on this connection. Populated whenever available is false.", "type": "string", "examples": [ "This connection uses Scalekit's shared slack app, and a webhook URL is registered against the app rather than the connection — the shared app has only one." ] }, "refusal_code": { "description": "The stable code of the connection-level rule that made this trigger unavailable. SHARED_APP — the connection uses Scalekit's shared provider app. POLL_CONNECTION_SCOPE — a polled trigger cannot be connection-scoped. UNSPECIFIED when the trigger is available, or when a rule without a code refused it; reason and remedy are populated either way.", "$ref": "#/components/schemas/triggersTriggerRefusalCode", "examples": [ "SHARED_APP" ] }, "register_hint": { "description": "Provider-specific guidance on where to register the connection's ingress URL in the provider's console, written by the connector author. At most 500 characters, with no control characters. Empty when the connector provides none, and always empty for a polled trigger.", "type": "string", "examples": [ "api.slack.com/apps → your app → Event Subscriptions → turn on Enable Events → paste into Request URL." ] }, "remedy": { "description": "What to do to make the trigger available. Populated whenever available is false.", "type": "string", "examples": [ "Add your own slack app to this connection, then subscribe." ] }, "required_scopes": { "description": "Permissions a connected account's grant must include to subscribe to this trigger. A subscription for an account whose grant lacks one of them is refused, naming the missing scope.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersRequiredScope" } }, "requires_signing_secret": { "description": "Whether the provider signs this trigger's events with a secret the customer copies from the provider's console and sets on the connection's ingress endpoint. Always false for a polled trigger, which receives no inbound requests.", "type": "boolean", "examples": [ true ] }, "secret_hint": { "description": "Provider-specific guidance on where the provider shows the signing secret to copy, written by the connector author. At most 500 characters, with no control characters. Empty when the connector provides none, and always empty for a polled trigger.", "type": "string", "examples": [ "Your app → Basic Information → App Credentials → Signing Secret." ] } } }, "triggersBatchCreateTriggerSubscriptionResult": { "description": "One account's result within a batch.", "type": "object", "properties": { "connected_account_id": { "description": "The connected account ID this result is for, as sent in the request.", "type": "string", "examples": [ "ca_123456789012345" ] }, "outcome": { "description": "What happened to this account. CREATED — a subscription was created. ALREADY_SUBSCRIBED — the account already had a subscription to this trigger with these exact config values; nothing new was created, and list subscriptions to read the existing one. REFUSED — the account cannot receive this trigger; reason says why and what to do. NOT_FOUND — no such account on this connection in this environment. FAILED — the attempt failed for a reason unrelated to the account; nothing was created, and retrying may succeed.", "$ref": "#/components/schemas/triggersBatchSubscribeOutcome", "examples": [ "CREATED" ] }, "reason": { "description": "Why the account was not subscribed, and for a refusal what to do about it, in one sentence — the same text CreateTriggerSubscription returns for the same account. Empty for CREATED.", "type": "string", "examples": [ "connected account not found" ] }, "subscription": { "description": "The created subscription, for CREATED. Absent for every other outcome, including ALREADY_SUBSCRIBED.", "$ref": "#/components/schemas/triggersTriggerSubscription" } } }, "triggersBatchCreateTriggerSubscriptionsResponse": { "type": "object", "properties": { "created_count": { "description": "How many subscriptions this call created. Excludes accounts that were already subscribed.", "type": "integer", "format": "int64", "examples": [ 98 ] }, "results": { "description": "One result per requested account, in the order the accounts were sent, so a client can pair them up positionally without matching on id. For a connection-scoped trigger subscribed with an empty connected_account_ids, exactly one result, with an empty connected_account_id.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersBatchCreateTriggerSubscriptionResult" } } } }, "triggersBatchDeleteOutcome": { "description": "What happened to one subscription in a batch delete.\n\n - BATCH_DELETE_OUTCOME_DELETED: The subscription was deleted by this call.\n - BATCH_DELETE_OUTCOME_NOT_FOUND: No such subscription on this connection\nin this environment — including one an earlier attempt already deleted, which is what makes retrying the whole batch safe. Another\nconnection's or another tenant's subscription is reported exactly like a missing one.\n - BATCH_DELETE_OUTCOME_FAILED: The delete could not be completed. It may\nor may not have happened; retrying is safe and answers DELETED or NOT_FOUND.\n - BATCH_DELETE_OUTCOME_NOT_ATTEMPTED: The request ran out of time before\nthis subscription was reached. Nothing was changed for it; send it again.", "type": "string", "enum": [ "BATCH_DELETE_OUTCOME_DELETED", "BATCH_DELETE_OUTCOME_NOT_FOUND", "BATCH_DELETE_OUTCOME_FAILED", "BATCH_DELETE_OUTCOME_NOT_ATTEMPTED" ] }, "triggersBatchDeleteTriggerSubscriptionResult": { "description": "One subscription's result within a batch delete.", "type": "object", "properties": { "connected_account_id": { "description": "For trigger_name with connected_account_ids, the account this result belongs to, as sent. Always empty for a subscription_ids request.", "type": "string", "examples": [ "ca_123456789012345" ] }, "outcome": { "description": "What happened to this subscription. BATCH_DELETE_OUTCOME_DELETED — deleted by this call. BATCH_DELETE_OUTCOME_NOT_FOUND — no such subscription on this connection in this environment, including one an earlier attempt already deleted; treat it like DELETED when retrying. BATCH_DELETE_OUTCOME_FAILED — the delete could not be completed and may or may not have happened; retrying is safe. BATCH_DELETE_OUTCOME_NOT_ATTEMPTED — the request ran out of time before reaching this subscription; nothing was changed for it, so send it again.", "$ref": "#/components/schemas/triggersBatchDeleteOutcome", "examples": [ "BATCH_DELETE_OUTCOME_DELETED" ] }, "reason": { "description": "One sentence explaining the outcome. Empty for BATCH_DELETE_OUTCOME_DELETED. Never contains internal error detail. The wording can change: match on outcome, not on this text.", "type": "string", "examples": [ "trigger subscription not found" ] }, "subscription_id": { "description": "The subscription this result is about. For subscription_ids, the ID exactly as sent. For trigger_name with connected_account_ids, a subscription found for the account; empty only on the single NOT_FOUND result of an account that held no matching subscription.", "type": "string", "examples": [ "trgs_28128748834787841" ] } } }, "triggersBatchDeleteTriggerSubscriptionsResponse": { "type": "object", "properties": { "deleted_count": { "description": "How many subscriptions this call deleted. Excludes NOT_FOUND results, so a subscription an earlier attempt already deleted is not counted again.", "type": "integer", "format": "int64", "examples": [ 2 ] }, "results": { "description": "For subscription_ids, one result per ID in the order sent, so a client can pair them up positionally. For trigger_name with connected_account_ids, the results are grouped by account in the order sent, ordered by ascending subscription ID within an account, with one NOT_FOUND result for an account that held no matching subscription.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersBatchDeleteTriggerSubscriptionResult" } } } }, "triggersBatchLookupOutcome": { "description": "What happened to one ID in a batch lookup.\n\n - BATCH_LOOKUP_OUTCOME_FOUND: The event was found; the result's delivery\nholds it.\n - BATCH_LOOKUP_OUTCOME_NOT_FOUND: No trigger event with this message ID or\nevent ID exists in this environment. An ID from another environment is reported exactly like a missing one.\n - BATCH_LOOKUP_OUTCOME_RATE_LIMITED: The read was refused for volume. The\nbatch stops: every ID that had not started by then is NOT_ATTEMPTED, wherever it sits in the list.\n - BATCH_LOOKUP_OUTCOME_FAILED: The lookup could not be completed; retrying\nmay succeed.\n - BATCH_LOOKUP_OUTCOME_NOT_ATTEMPTED: Not looked up, because an earlier ID\nwas rate limited or the request ran out of time.", "type": "string", "enum": [ "BATCH_LOOKUP_OUTCOME_FOUND", "BATCH_LOOKUP_OUTCOME_NOT_FOUND", "BATCH_LOOKUP_OUTCOME_RATE_LIMITED", "BATCH_LOOKUP_OUTCOME_FAILED", "BATCH_LOOKUP_OUTCOME_NOT_ATTEMPTED" ] }, "triggersBatchLookupTriggerDeliveriesRequest": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "description": "Message IDs (`msg_…`, sent to the endpoint as the `webhook-id` header) or event IDs (the payload's `dedupe_key`) of the trigger events to find, in any mix: at least 1 and at most 25, with no repeats. Each is 1 to 256 characters: letters, digits, `.`, `_` and `-`. An attempt ID (`atmpt_…`) refuses the whole request.", "type": "array", "items": { "type": "string" }, "examples": [ [ "msg_2yAqUxVq4mTt8jHZ3fWbKcN1Pd0", "ca_5F28128748834787840.trgs_5F28128748834787841.Ev07ABCDEF12" ] ] } } }, "triggersBatchLookupTriggerDeliveriesResponse": { "type": "object", "properties": { "found_count": { "description": "How many of the requested IDs were found.", "type": "integer", "format": "int64", "examples": [ 24 ] }, "results": { "description": "One result per requested ID, in the order the IDs were sent, so a client can pair them up positionally.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersBatchLookupTriggerDeliveryResult" } } } }, "triggersBatchLookupTriggerDeliveryResult": { "description": "One ID's result within a batch lookup.", "type": "object", "properties": { "delivery": { "description": "The event and its delivery attempts to every endpoint, oldest first, as LookupTriggerDelivery returns them, except that no attempt carries a response body: each attempt's `response` is empty and its `response_truncated` is false. `truncated` keeps its meaning: true when the event has more than the 50 attempts returned. Present only for BATCH_LOOKUP_OUTCOME_FOUND.", "$ref": "#/components/schemas/triggersLookupTriggerDeliveryResponse" }, "id": { "description": "The ID this result is about, exactly as sent.", "type": "string", "examples": [ "msg_2yAqUxVq4mTt8jHZ3fWbKcN1Pd0" ] }, "outcome": { "description": "What happened to this ID. BATCH_LOOKUP_OUTCOME_FOUND — the event was found and delivery holds it. BATCH_LOOKUP_OUTCOME_NOT_FOUND — no trigger event with this message ID or event ID exists in this environment. BATCH_LOOKUP_OUTCOME_RATE_LIMITED — the read was refused for volume; look the ID up again shortly. BATCH_LOOKUP_OUTCOME_FAILED — the lookup could not be completed; retrying may succeed. BATCH_LOOKUP_OUTCOME_NOT_ATTEMPTED — not looked up, because an earlier ID was rate limited or the request ran out of time; send it again.", "$ref": "#/components/schemas/triggersBatchLookupOutcome", "examples": [ "BATCH_LOOKUP_OUTCOME_FOUND" ] }, "reason": { "description": "One sentence explaining the outcome. Empty for BATCH_LOOKUP_OUTCOME_FOUND. Never contains internal error detail. The wording can change: match on outcome, not on this text.", "type": "string", "examples": [ "no trigger delivery with this id exists in this environment" ] } } }, "triggersBatchResendOutcome": { "description": "What happened to one target in a batch resend.\n\n - BATCH_RESEND_OUTCOME_QUEUED: A new manual delivery attempt was queued.\nNot yet delivered: its outcome appears with the message's other attempts.\n - BATCH_RESEND_OUTCOME_NOT_FOUND: The message or the endpoint does not exist\nin this environment's trigger delivery application. Another environment's IDs are reported exactly like missing ones.\n - BATCH_RESEND_OUTCOME_RATE_LIMITED: Refused for volume. The batch stops:\nevery target that had not started by then is NOT_ATTEMPTED, wherever it sits in the list.\n - BATCH_RESEND_OUTCOME_FAILED: No new attempt could be confirmed as queued.\nA target whose request timed out may still have been queued, so retrying it can queue a second attempt. A target whose event payload is no\nlonger stored is also FAILED, and resending it can never succeed; its reason says so.\n - BATCH_RESEND_OUTCOME_NOT_ATTEMPTED: Not sent, because an earlier target\nwas rate limited or the request ran out of time. Nothing was queued for it.", "type": "string", "enum": [ "BATCH_RESEND_OUTCOME_QUEUED", "BATCH_RESEND_OUTCOME_NOT_FOUND", "BATCH_RESEND_OUTCOME_RATE_LIMITED", "BATCH_RESEND_OUTCOME_FAILED", "BATCH_RESEND_OUTCOME_NOT_ATTEMPTED" ] }, "triggersBatchResendTriggerDeliveriesRequest": { "description": "The deliveries to retry. A repeated msg_id and endpoint_id pair is refused by the service:\nunique cannot be declared on a list of messages, and sending the pair twice would queue two\nattempts.", "type": "object", "required": [ "targets" ], "properties": { "targets": { "description": "The deliveries to retry, each a message ID and an endpoint ID: at least 1 and at most 50. A msg_id and endpoint_id pair may appear only once; a repeated pair refuses the whole request rather than queueing two attempts. The same message may appear with different endpoints, and the same endpoint with different messages.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerDeliveryResendTarget" } } } }, "triggersBatchResendTriggerDeliveriesResponse": { "type": "object", "properties": { "queued_count": { "description": "How many new delivery attempts this call queued.", "type": "integer", "format": "int64", "examples": [ 12 ] }, "results": { "description": "One result per target, in the order the targets were sent, so a client can pair them up positionally.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersBatchResendTriggerDeliveryResult" } } } }, "triggersBatchResendTriggerDeliveryResult": { "description": "One target's result within a batch resend.", "type": "object", "properties": { "endpoint_id": { "description": "Endpoint ID of the target, exactly as sent.", "type": "string", "examples": [ "ep_2yAqUuFkqbL5nXvC7HhWJRY6Gg9" ] }, "msg_id": { "description": "Message ID of the target, exactly as sent.", "type": "string", "examples": [ "msg_2yAqUxVq4mTt8jHZ3fWbKcN1Pd0" ] }, "outcome": { "description": "What happened to this target. BATCH_RESEND_OUTCOME_QUEUED — a new manual attempt was queued; it has not been delivered yet. BATCH_RESEND_OUTCOME_NOT_FOUND — the message or the endpoint does not exist in this environment. BATCH_RESEND_OUTCOME_RATE_LIMITED — refused for volume; send this target again shortly. BATCH_RESEND_OUTCOME_FAILED — no new attempt could be confirmed as queued; one whose request timed out may still have been, so a retry can queue a second attempt. A target whose event payload is no longer stored is also FAILED, with a reason saying it cannot be resent; retrying it will not help. BATCH_RESEND_OUTCOME_NOT_ATTEMPTED — not sent, because an earlier target was rate limited or the request ran out of time; nothing was queued for it.", "$ref": "#/components/schemas/triggersBatchResendOutcome", "examples": [ "BATCH_RESEND_OUTCOME_QUEUED" ] }, "reason": { "description": "One sentence explaining the outcome. Empty for BATCH_RESEND_OUTCOME_QUEUED. Never contains internal error detail. The wording can change: match on outcome, not on this text.", "type": "string", "examples": [ "not attempted: an earlier target was rate limited; resend this target shortly" ] } } }, "triggersBatchSubscribeOutcome": { "description": "What happened to one account in a batch.\n\n - CREATED: A subscription was created for this account.\n - ALREADY_SUBSCRIBED: This account already had a subscription to this trigger\nwith this exact filter, so nothing new was created. Not an error — it is what makes retrying a partly-failed batch safe.\n - REFUSED: This account cannot receive this trigger. reason and remedy say\nwhy and what to do.\n - NOT_FOUND: No such account on this connection, in this environment.\n - FAILED: The attempt failed for a reason unrelated to this account — nothing\nwas created for it, and retrying it may succeed.", "type": "string", "enum": [ "CREATED", "ALREADY_SUBSCRIBED", "REFUSED", "NOT_FOUND", "FAILED" ] }, "triggersConfigField": { "description": "A value a subscriber can set on a subscription to this trigger, such as the channel to watch.\n\nDerived from the conditions the trigger matches events on, so every field listed here is read by\none of those conditions.", "type": "object", "properties": { "display_name": { "description": "Human-readable label for the field.", "type": "string", "examples": [ "Channel" ] }, "help_text": { "description": "Guidance on what to enter. Empty when the trigger provides none.", "type": "string", "examples": [ "The ID of the channel to watch for new messages." ] }, "key": { "description": "The key to send in a subscription's config map. Send it exactly as returned, without changing its case: a key that does not match is refused.", "type": "string", "examples": [ "channel" ] }, "placeholder": { "description": "Example value to show in an empty input. Empty when the trigger provides none.", "type": "string", "examples": [ "C0123456789" ] }, "required": { "description": "Whether a subscription must set this field to a non-empty value. A subscription request that omits a required field is refused.", "type": "boolean", "examples": [ true ] } } }, "triggersEligibleAccount": { "description": "A connected account, with whether it can receive a particular trigger.", "type": "object", "properties": { "eligible": { "description": "Whether this account can be subscribed to the trigger. When false, reason and remedy explain why and what to do.", "type": "boolean", "examples": [ true ] }, "health": { "description": "The account's own state, evaluated for what this trigger needs captured on the account: a webhook trigger needs the provider workspace, and an account-scoped webhook trigger also needs the provider user. A polled trigger needs neither, so the same account can be READY for one trigger and AWAITING_CONFIRMATION for another. Carried alongside eligible because they answer different questions: eligible is whether this trigger can be subscribed on this account, health is the account's own state and the single action that resolves it.", "$ref": "#/components/schemas/triggersAccountHealth" }, "id": { "description": "ID of the connected account. Pass it as connected_account_id when creating a subscription.", "type": "string", "examples": [ "ca_123456789012345" ] }, "identifier": { "description": "The identifier the connected account was created with: the value you passed as identifier, such as your app's user ID or the user's email address. When the account has no identifier, this is the connected account ID.", "type": "string", "examples": [ "user_123" ] }, "reason": { "description": "Why this account cannot receive the trigger. Populated whenever eligible is false.", "type": "string", "examples": [ "This account was authorized under a different app than the connection now uses." ] }, "remedy": { "description": "What to do so the account can receive the trigger. Populated whenever eligible is false.", "type": "string", "examples": [ "Re-authorize this account under your app, then subscribe." ] } } }, "triggersGenerateTriggerSigningSecretResponse": { "description": "The one response in this API that carries a signing secret in plain text, and the only time\nyou ever see it: endpoint shows the secret masked, as every other webhook URL response does, and\nthe plain text appears only in signing_secret and url_with_secret.", "type": "object", "properties": { "endpoint": { "description": "The connection's webhook endpoint after the secret was stored, rendered exactly as GetTriggerIngressEndpoint renders it: the secret appears here only in masked form, and rotation_in_progress is true when this call started a rotation.", "$ref": "#/components/schemas/triggersTriggerIngressEndpoint" }, "signing_secret": { "description": "The generated secret, in plain text. Returned only in this response and never again by any endpoint, nor written to a log. The provider presents it back on every event in exactly one of three ways: an `Authorization: Bearer ` header, the `X-Scalekit-Webhook-Secret` header, or the final path segment of url_with_secret.", "type": "string" }, "url_with_secret": { "description": "endpoint.url with the secret appended as a final path segment. Paste this into the provider's console when the provider cannot send a custom header. It is as sensitive as signing_secret and is likewise returned only in this response.", "type": "string" } } }, "triggersGetTriggerActivityResponse": { "description": "What happened to this environment's trigger events, and what this cannot tell you.", "type": "object", "properties": { "counts": { "description": "Event counts over the window, keyed by outcome. Every key is always present, zeroes included. received — events that arrived at one of the environment's webhook URLs, including those that then failed signature verification. filtered — verified events that no subscription's filter or account matched. unresolved — verified events for a provider workspace that no connected account holds. delivered — events handed off for delivery to your endpoints; this does not confirm that your endpoint received them. delivery_failed — events whose handoff for delivery failed. duplicate — repeated deliveries of an event already received, such as provider retries, which are ignored. signature_failed — events that failed signature verification. discarded — events received while Triggers was not enabled for the environment, and dropped.", "type": "object", "additionalProperties": { "type": "string", "format": "int64" }, "examples": [ { "delivered": 88, "delivery_failed": 0, "discarded": 0, "duplicate": 5, "filtered": 30, "received": 120, "signature_failed": 0, "unresolved": 2 } ] }, "degraded": { "description": "True when some counts could not be read, so the counts are incomplete. Do not read zero counts as \"nothing arrived\" while this is true.", "type": "boolean", "examples": [ false ] }, "delivery_details_path": { "description": "Path, relative to the Scalekit dashboard, of the trigger delivery page. That page shows each delivery attempt to your endpoints, including failures after an event was handed off for delivery.", "type": "string", "examples": [ "/trigger-delivery" ] }, "explains_individual_events": { "description": "Always false. Trigger events are not stored individually, so no endpoint can explain what happened to one specific event. Show this limitation to the user rather than hiding it.", "type": "boolean", "examples": [ false ] }, "signature_banner": { "description": "True when at least 5 events in the window failed signature verification and they make up at least half of the events received. This usually means the signing secret set on a connection does not match the provider's. Show it prominently: a provider can disable a webhook URL that keeps failing, and re-enabling it is a manual step in the provider's app configuration.", "type": "boolean", "examples": [ false ] }, "window_hours": { "description": "How many hours back the counts reach, ending now.", "type": "integer", "format": "int32", "examples": [ 24 ] } } }, "triggersGetTriggerUsageResponse": { "description": "Metered trigger deliveries in hourly buckets for period 24h, or in UTC daily buckets for every\nother request. Buckets with no deliveries are left out.", "type": "object", "properties": { "bucket": { "description": "What each entry counts. `TRIGGER_USAGE_BUCKET_HOUR` for `period=24h`, whose counts are in `hours`. `TRIGGER_USAGE_BUCKET_DAY` for `period=7d` and `period=30d`, whose counts are in `days`. `TRIGGER_USAGE_BUCKET_UNSPECIFIED` when the request used `from` and `to`; those counts are always by UTC day, in `days`.", "$ref": "#/components/schemas/triggersTriggerUsageBucket", "examples": [ "TRIGGER_USAGE_BUCKET_HOUR" ] }, "current_hour": { "description": "Only for `period=24h`, and empty otherwise. The start of the UTC clock hour in progress on the server, as an RFC 3339 timestamp in UTC (`Z`). It is the last of the 24 hours `hours` covers, and its count grows until the hour ends. Returned so a client lays out the 24 hours and marks the one in progress without relying on its own clock.", "type": "string", "examples": [ "2026-10-14T18:00:00Z" ] }, "days": { "description": "One entry per UTC day within the range read (`from`..`to`) that has metered deliveries, oldest first. A day in that range with none is absent rather than listed as zero, so a client that needs a continuous series fills the missing days itself, over the returned `from` and `to` rather than the range it requested. Days outside the range read were not read and must not be drawn as zero. Always empty for `period=24h`, whose counts are in `hours`.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerUsageDay" } }, "from": { "description": "First UTC calendar date of the range read, as YYYY-MM-DD. For a `from` and `to` request, the requested `from`, or the first day of the readable window, 30 days before `today`, when the request started earlier. For a `period` request, the UTC date of the first hour (`24h`) or the first day (`7d`, `30d`) of the period.", "type": "string", "examples": [ "2026-10-01" ] }, "hours": { "description": "Only for `period=24h`, and empty otherwise. One entry per UTC clock hour that has metered deliveries, oldest first, among the 24 hours from 23 hours before `current_hour` through `current_hour`. An hour in that range with none is absent rather than listed as zero, so a client that needs a continuous series fills the missing hours itself over those 24 hours. Hours outside them were not read and must not be drawn.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerUsageHour" } }, "period": { "description": "The `period` the request asked for: `24h`, `7d` or `30d`. Empty when the request used `from` and `to`.", "type": "string", "examples": [ "24h" ] }, "to": { "description": "Last UTC calendar date of the range read, as YYYY-MM-DD. For a `from` and `to` request, the requested `to`, or `today` when the request ended later. For a `period` request, always `today`.", "type": "string", "examples": [ "2026-10-31" ] }, "today": { "description": "The server's current UTC calendar date, as YYYY-MM-DD. Deliveries on this day are still being metered, so its count grows until the day ends. The readable window and any clamping of `from` and `to` are measured from this date. Returned so a client tells the day in progress apart from completed days without relying on its own clock.", "type": "string", "examples": [ "2026-10-31" ] } } }, "triggersListAvailableTriggersResponse": { "type": "object", "properties": { "connection_uses_shared_app": { "description": "Whether the connection is configured to use Scalekit's shared provider app rather than the customer's own. Read from the connection's saved configuration. When true, any trigger with platform_credentials UNSUPPORTED is unavailable until the customer adds their own provider app to the connection.", "type": "boolean", "examples": [ false ] }, "triggers": { "description": "Every trigger the connection's provider publishes, including unavailable ones. Check available on each before offering it.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersAvailableTrigger" } } } }, "triggersListEligibleAccountsResponse": { "type": "object", "properties": { "accounts": { "description": "One page of the connection's connected accounts, eligible and ineligible, each with its health for this trigger.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersEligibleAccount" } }, "next_page_token": { "description": "Pass as page_token to read the next page. Empty when there is no next page.", "type": "string", "examples": [ "" ] }, "prev_page_token": { "description": "Pass as page_token to read the previous page. Empty when there is no previous page.", "type": "string", "examples": [ "" ] }, "total_size": { "description": "How many of this connection's accounts match the query, across every page. Accounts on other connections are never counted.", "type": "integer", "format": "int64", "examples": [ 104 ] } } }, "triggersListTriggerDeliveriesByEndpointResponse": { "type": "object", "properties": { "deliveries": { "description": "One page of the endpoint's deliveries that match the filters, newest first.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerDelivery" } }, "next_page_token": { "description": "Pass this as page_token, with the same endpoint_id and filters, to read the next page of older deliveries. Empty when there are no older deliveries.", "type": "string", "examples": [ "" ] } } }, "triggersListTriggerDeliveryAttemptsByEndpointResponse": { "type": "object", "properties": { "attempts": { "description": "The endpoint's most recent delivery attempts, newest first.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerDeliveryAttempt" } } } }, "triggersListTriggerDeliveryAttemptsByMessageResponse": { "type": "object", "properties": { "attempts": { "description": "The delivery's attempts to this endpoint, oldest first.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerDeliveryAttempt" } }, "truncated": { "description": "True when the delivery has more than the 50 attempts returned. The newest 50 are returned, so the first attempt is missing when this is true.", "type": "boolean" } } }, "triggersListTriggerSubscriptionsResponse": { "type": "object", "properties": { "next_page_token": { "description": "Pass as page_token to read the next page. Empty when there is no next page.", "type": "string", "examples": [ "" ] }, "prev_page_token": { "description": "Pass as page_token to read the previous page. Empty when there is no previous page.", "type": "string", "examples": [ "" ] }, "status_counts": { "description": "How many subscriptions sit in each status, keyed by the status name. Counted over the whole matching set rather than the current page, so a client can show per-status totals without fetching every page. Honours trigger_name but ignores statuses, so the totals stay still while a customer switches between status filters.", "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "examples": [ { "ACTIVE": 93, "PAUSED": 3, "PAUSED_CREDENTIAL": 4 } ] }, "subscriptions": { "description": "One page of the connection's trigger subscriptions that match the filters, newest first.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerSubscription" } }, "total_size": { "description": "How many subscriptions match the filters in total, across every page.", "type": "integer", "format": "int64", "examples": [ 100 ] } } }, "triggersLookupTriggerDeliveryResponse": { "type": "object", "properties": { "attempts": { "description": "The event's delivery attempts to every endpoint in this environment, oldest first. Each names the endpoint_id and endpoint_url it was sent to.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/triggersTriggerDeliveryAttempt" } }, "connection_id": { "description": "ID of the connection the event came from. Present even after the connection is deleted. Empty when the event carries none.", "type": "string", "examples": [ "conn_28128748834787840" ] }, "connection_key_id": { "description": "Key ID of the connection the event came from. Empty when the connection no longer exists.", "type": "string", "examples": [ "salesforce-acme" ] }, "connection_provider": { "description": "Provider of the connection the event came from. Empty when the connection no longer exists.", "type": "string", "examples": [ "SALESFORCE" ] }, "event_id": { "description": "Event ID of the event: the payload's `dedupe_key` and `correlation_id`. Empty when the event was sent without one.", "type": "string", "examples": [ "ca_5F28128748834787840.trgs_5F28128748834787841.Ev07ABCDEF12" ] }, "message_timestamp": { "description": "When the event was accepted for delivery.", "type": "string", "format": "date-time", "examples": [ "2026-10-09T12:34:55Z" ] }, "msg_id": { "description": "Message ID of the event, sent to each endpoint as the `webhook-id` header.", "type": "string", "examples": [ "msg_2yAqUxVq4mTt8jHZ3fWbKcN1Pd0" ] }, "subscription_id": { "description": "ID of the trigger subscription that sent the event. Present even after the subscription is deleted. Empty when the event carries none.", "type": "string", "examples": [ "trgs_28128748834787841" ] }, "trigger_mode": { "description": "How the trigger detects events, from the newest version of its definition: WEBHOOK or POLL. TRIGGER_MODE_UNSPECIFIED when the subscription or the definition no longer exists.", "$ref": "#/components/schemas/triggersTriggerMode", "examples": [ "POLL" ] }, "trigger_name": { "description": "Key of the trigger that fired, as the subscription was created with. Empty when the subscription no longer exists.", "type": "string", "examples": [ "slack_message_posted" ] }, "truncated": { "description": "True when the event has more than the 50 attempts returned. The newest 50 are returned, so the earliest attempts are missing when this is true.", "type": "boolean" } } }, "triggersRecoverTriggerDeliveriesResponse": { "description": "A recovery that has started. Its outcome is not reported: the recovery runs in the background,\nand no record of it can be read back through the API.", "type": "object", "properties": { "status": { "description": "The recovery's state when this call returned. `running` in practice: the recovery continues after the response, and its later state is not reported.", "type": "string", "examples": [ "running" ] }, "task_id": { "description": "Identifies this recovery in Scalekit's logs; quote it when contacting support. It cannot be looked up or polled through the API.", "type": "string", "examples": [ "qtask_2yAqV1pZbF8sRj3nWkXcT5mLh0" ] } } }, "triggersRequiredScope": { "description": "A permission the trigger needs on the connected account's grant.", "type": "object", "properties": { "grant": { "description": "Which grant channel must carry the scope. Some providers fan events out differently for a bot install than for a user install, so this is not merely descriptive.", "type": "string", "examples": [ "bot" ] }, "scope": { "description": "The provider's own name for the permission, exactly as it appears in their console.", "type": "string", "examples": [ "channels:history" ] } } }, "triggersTriggerDelivery": { "description": "One trigger event's delivery to one endpoint: a single entry however many attempts it took.", "type": "object", "properties": { "connection_id": { "description": "ID of the connection the event came from. Present even after the connection is deleted. Empty when the event carries none.", "type": "string", "examples": [ "conn_28128748834787840" ] }, "connection_key_id": { "description": "Key ID of the connection the event came from. Empty when the connection no longer exists.", "type": "string", "examples": [ "slack-acme" ] }, "connection_provider": { "description": "Provider of the connection the event came from. Empty when the connection no longer exists.", "type": "string", "examples": [ "SLACK" ] }, "endpoint_id": { "description": "ID of the endpoint the event was delivered to.", "type": "string", "examples": [ "ep_2yAqUuFkqbL5nXvC7HhWJRY6Gg9" ] }, "event_id": { "description": "Event ID of the event: the payload's `dedupe_key` and `correlation_id`. Empty when the event was sent without one.", "type": "string", "examples": [ "ca_5F28128748834787840.trgs_5F28128748834787841.Ev07ABCDEF12" ] }, "message_timestamp": { "description": "When the event was accepted for delivery.", "type": "string", "format": "date-time", "examples": [ "2026-10-09T12:34:55Z" ] }, "msg_id": { "description": "Message ID of the event, sent to the endpoint as the `webhook-id` header.", "type": "string", "examples": [ "msg_2yAqUxVq4mTt8jHZ3fWbKcN1Pd0" ] }, "next_attempt_at": { "description": "When the next attempt is scheduled. Present only while status is TRIGGER_DELIVERY_STATUS_RETRYING.", "type": "string", "format": "date-time", "examples": [ "2026-10-09T12:39:56Z" ] }, "status": { "description": "The delivery's state across all its attempts.", "$ref": "#/components/schemas/triggersTriggerDeliveryStatus", "examples": [ "TRIGGER_DELIVERY_STATUS_RETRYING" ] }, "subscription_id": { "description": "ID of the trigger subscription that sent the event. Present even after the subscription is deleted. Empty when the event carries none.", "type": "string", "examples": [ "trgs_28128748834787841" ] }, "trigger_mode": { "description": "How the trigger detects events, from the newest version of its definition: WEBHOOK or POLL. The trigger's mode now, not a record of how this one event was detected. TRIGGER_MODE_UNSPECIFIED when the subscription or the definition no longer exists.", "$ref": "#/components/schemas/triggersTriggerMode", "examples": [ "WEBHOOK" ] }, "trigger_name": { "description": "Key of the trigger that fired, as the subscription was created with. Empty when the subscription no longer exists.", "type": "string", "examples": [ "slack_message_posted" ] } } }, "triggersTriggerDeliveryAttempt": { "type": "object", "properties": { "endpoint_id": { "description": "ID of the endpoint this attempt was made against.", "type": "string", "examples": [ "ep_123456789012345" ] }, "endpoint_url": { "description": "URL this attempt was sent to.", "type": "string", "examples": [ "https://agent.example.com/hooks/triggers" ] }, "id": { "description": "ID of this delivery attempt.", "type": "string", "examples": [ "atmpt_123456789012345" ] }, "msg_id": { "description": "ID of the trigger event message this attempt delivered. Every attempt to deliver the same event shares this ID.", "type": "string", "examples": [ "msg_123456789012345" ] }, "response": { "description": "Response body the endpoint returned for this attempt. A long body may be truncated.", "type": "string", "examples": [ "{\"ok\":true}" ] }, "response_duration_ms": { "description": "How long the endpoint took to respond to this attempt, in milliseconds.", "type": "integer", "format": "int32", "examples": [ 182 ] }, "response_status_code": { "description": "HTTP status code the endpoint returned for this attempt.", "type": "integer", "format": "int32", "examples": [ 200 ] }, "response_truncated": { "description": "True when `response` was cut to its first 4096 bytes. Set only by ListTriggerDeliveryAttemptsByMessage and LookupTriggerDelivery, which apply that cap.", "type": "boolean" }, "status": { "description": "Whether this attempt succeeded, is still in flight, failed, or was canceled. A failed delivery is retried, so FAIL on one attempt does not mean the event was never delivered — check the newest attempt for that message.", "$ref": "#/components/schemas/triggersTriggerDeliveryAttemptStatus", "examples": [ "SUCCESS" ] }, "timestamp": { "description": "When this attempt was made.", "type": "string", "format": "date-time", "examples": [ "2026-10-09T12:34:56Z" ] }, "trigger_type": { "description": "Why this attempt was made: TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_SCHEDULED for the first attempt or an automatic retry, TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_MANUAL for a retry someone started by hand.", "$ref": "#/components/schemas/triggersTriggerDeliveryAttemptTriggerType", "examples": [ "TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_SCHEDULED" ] } } }, "triggersTriggerDeliveryAttemptStatus": { "description": "The outcome of one delivery attempt.\n\n - SUCCESS: The endpoint accepted the delivery.\n - PENDING: The attempt is waiting to be sent.\n - FAIL: The attempt failed. Failed deliveries are retried.\n - SENDING: The attempt is being sent.\n - CANCELED: The attempt was canceled and will not be sent.", "type": "string", "enum": [ "SUCCESS", "PENDING", "FAIL", "SENDING", "CANCELED" ] }, "triggersTriggerDeliveryAttemptTriggerType": { "description": "Why a delivery attempt was made.\n\n - TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_SCHEDULED: The first attempt or an\nautomatic retry on the delivery schedule.\n - TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_MANUAL: A retry someone started by\nhand.", "type": "string", "enum": [ "TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_SCHEDULED", "TRIGGER_DELIVERY_ATTEMPT_TRIGGER_TYPE_MANUAL" ] }, "triggersTriggerDeliveryResendTarget": { "description": "One delivery to retry: a trigger event and the endpoint to deliver it to again.", "type": "object", "required": [ "msg_id", "endpoint_id" ], "properties": { "endpoint_id": { "description": "ID of the delivery endpoint to deliver the event to again: `ep_` followed by 1 to 64 letters or digits.", "type": "string", "examples": [ "ep_2yAqUuFkqbL5nXvC7HhWJRY6Gg9" ] }, "msg_id": { "description": "Message ID of the trigger event to deliver again, as returned in msg_id by ListTriggerDeliveriesByEndpoint: `msg_` followed by 1 to 64 letters or digits.", "type": "string", "examples": [ "msg_2yAqUxVq4mTt8jHZ3fWbKcN1Pd0" ] } } }, "triggersTriggerDeliveryScope": { "description": "Whether a trigger delivers once per connected account or once for the whole connection.\n\nSet by the trigger, not chosen by the subscriber. A polled trigger polls with one connected\naccount's credential, so a polled trigger that is connection-scoped is reported as unavailable.\n\n - ACCOUNT: One event per subscribed connected account. For a webhook trigger,\nan event is delivered for an account only when the event's provider workspace and user match the account's; a polled\ntrigger polls each account with that account's own credential. Subscribed on a specific\nconnected account.\n - CONNECTION: One event for the whole connection, whatever accounts exist\non it. Subscribed on the connection itself, naming no account.", "type": "string", "enum": [ "ACCOUNT", "CONNECTION" ] }, "triggersTriggerDeliveryStatus": { "description": "The state of one trigger event's delivery to one endpoint, across all its attempts.\n\nThe values carry the enum's name as a prefix because enum values share one namespace across this\npackage, where PENDING and FAILED are already taken.\n\n - TRIGGER_DELIVERY_STATUS_DELIVERED: An attempt succeeded. No further attempt\nis made.\n - TRIGGER_DELIVERY_STATUS_PENDING: Accepted for delivery; no attempt has\nfinished yet.\n - TRIGGER_DELIVERY_STATUS_FAILED: Every scheduled attempt failed. No further\nattempt is made unless one is started by hand.\n - TRIGGER_DELIVERY_STATUS_RETRYING: An attempt failed and another is scheduled,\nat next_attempt_at.", "type": "string", "enum": [ "TRIGGER_DELIVERY_STATUS_DELIVERED", "TRIGGER_DELIVERY_STATUS_PENDING", "TRIGGER_DELIVERY_STATUS_FAILED", "TRIGGER_DELIVERY_STATUS_RETRYING" ] }, "triggersTriggerIngressEndpoint": { "description": "The webhook URL a provider sends a connection's events to, and the state of the secret those\nevents are signed with.\n\nThis message never carries the signing secret itself: masked_signing_secret shows at most its\nlast four characters, so you can tell which secret is stored. The only response that returns a\nsecret in plaintext is GenerateTriggerSigningSecret's, once, for a secret Scalekit generates.", "type": "object", "properties": { "connection_id": { "description": "ID of the connection this webhook URL belongs to.", "type": "string", "examples": [ "conn_28128748834787840" ] }, "id": { "description": "Unique identifier of the connection's webhook endpoint.", "type": "string", "examples": [ "tie_28128748834787840" ] }, "masked_signing_secret": { "description": "The stored secret with all but its last four characters replaced, or every character replaced for a secret of 8 characters or fewer. Present only when one is configured. Enough to compare against the secret the provider's app configuration shows, and never enough to sign with.", "type": "string", "examples": [ "************************a4f9" ] }, "previous_signing_secret_expires_at": { "description": "When the previous secret stops being accepted even if the rotation is never confirmed: 24 hours after the rotation started. Absent when no rotation is in progress.", "type": "string", "format": "date-time" }, "rotation_in_progress": { "description": "Whether the previous signing secret is still accepted alongside the current one. True from the moment a different secret replaces a stored one until the rotation is confirmed, or until previous_signing_secret_expires_at passes.", "type": "boolean", "examples": [ false ] }, "signing_secret_configured": { "description": "Whether a signing secret is stored. While false, every event sent to the URL is answered with 503 so the provider retries it, and the provider's own URL verification fails.", "type": "boolean", "examples": [ true ] }, "signing_secret_rotation_id": { "description": "Identifies the latest signing-secret rotation; it increases by one each time a rotation starts. Zero when none has ever started. Pass this value to ConfirmTriggerSigningSecretRotation to confirm this specific rotation. A value naming a rotation that a newer one has since replaced is refused rather than confirming the wrong rotation.", "type": "string", "format": "int64", "examples": [ 3 ] }, "url": { "description": "The URL to paste into the provider's app configuration as the event destination. It is built on your environment's domain, using its custom domain when one is set, and ends in a random token unique to this connection, so treat it as confidential. Returned whether or not a signing secret has been set. The URL accepts request bodies up to 1 MB and answers a larger one with 413. Until a signing secret is set it answers events with 503, so the provider retries them; an event that fails signature verification is answered with 400.", "type": "string", "examples": [ "https://acme.scalekit.dev/triggers/v1/kq3T9vX2bL8mN4pR7sW1yZ" ] } } }, "triggersTriggerMode": { "description": "How a trigger detects that something happened.\n\n - WEBHOOK: The provider posts to a Scalekit URL when the event occurs.\n - POLL: Scalekit walks the provider's list on a cadence.", "type": "string", "enum": [ "WEBHOOK", "POLL" ] }, "triggersTriggerPlatformCredentials": { "description": "Whether a trigger works on a connection that uses Scalekit's shared provider app.\n\n - SUPPORTED: The trigger works on Scalekit's shared provider app as well\nas on the customer's own app.\n - UNSUPPORTED: The trigger needs the customer's own provider app on the connection\n— for example because a webhook URL is registered against the app, and the shared app has only one.", "type": "string", "enum": [ "SUPPORTED", "UNSUPPORTED" ] }, "triggersTriggerPollErrorCode": { "description": "Why a poll subscription's most recent run failed.\n\n - RATE_LIMITED: The provider asked Scalekit to slow down. Polling resumes\nafter backoff_until.\n - CREDENTIAL_REVOKED: The connected account's authorization was revoked or\nhas expired. Reconnect the account.\n - INVALID_CONFIGURATION: The subscription's configuration does not produce\na valid request for this trigger. Update the subscription's configuration.\n - PROVIDER_ERROR: The provider returned an error. Retried on the next run.\n - DELIVERY_FAILED: Events could not be handed to the delivery service. Retried\non the next run.\n - TIMED_OUT: The run timed out before it finished. Retried on the next run.\n - POLL_FAILED: The run failed for a reason none of the other codes describes.\nRetried on the next run.", "type": "string", "enum": [ "RATE_LIMITED", "CREDENTIAL_REVOKED", "INVALID_CONFIGURATION", "PROVIDER_ERROR", "DELIVERY_FAILED", "TIMED_OUT", "POLL_FAILED" ] }, "triggersTriggerPollState": { "description": "The state of a poll subscription's feed, as of its most recent run.\n\nRead from the feed's own stored state on every request rather than derived, so a feed that is\nfailing, rate limited, or held off is visible without looking at logs. A subscription whose\nstatus is ACTIVE can still be failing every run; this is where that shows.", "type": "object", "properties": { "backoff_until": { "description": "Polling is held off until this time, because the provider asked Scalekit to slow down or a run failed in a way retrying cannot fix. Absent when no hold-off has been recorded. A time in the past means the hold-off has ended and the next scheduled run polls again.", "type": "string", "format": "date-time" }, "consecutive_failures": { "description": "How many runs in a row have failed. Zero after any successful run.", "type": "integer", "format": "int64" }, "last_error": { "description": "A short, human-readable explanation of why the most recent run failed and what happens next. Empty when the most recent run succeeded or no run has happened yet. Chosen from a fixed set of messages by last_error_code and never contains the provider's response. The wording can change: match on last_error_code, not on this text.", "type": "string", "examples": [ "The provider is rate-limiting requests. Polling resumes automatically after a backoff." ] }, "last_error_code": { "description": "Why the most recent run failed, as a stable code to branch on. TRIGGER_POLL_ERROR_CODE_UNSPECIFIED when the most recent run succeeded or no run has happened yet. CREDENTIAL_REVOKED and INVALID_CONFIGURATION need a change from the customer before polling can succeed; every other code is retried automatically.", "$ref": "#/components/schemas/triggersTriggerPollErrorCode", "examples": [ "RATE_LIMITED" ] }, "last_run_at": { "description": "When Scalekit last polled the provider for this subscription, whether or not the run succeeded. Absent until the first run. A value far older than the effective interval means the feed has stopped running.", "type": "string", "format": "date-time" }, "watermark_updated_at": { "description": "When the feed's position last moved forward — the last time a run found and delivered newer events. A run that finds nothing new leaves it unchanged.", "type": "string", "format": "date-time" } } }, "triggersTriggerRefusalCode": { "description": "Which connection-level rule made a trigger unavailable, as a stable code a client can branch on\ninstead of parsing the human-readable reason.\n\n - SHARED_APP: The connection uses Scalekit's shared provider app and the\ntrigger needs the customer's own.\n - POLL_CONNECTION_SCOPE: The trigger is polled and connection-scoped, which\nthe poll path does not support.", "type": "string", "enum": [ "SHARED_APP", "POLL_CONNECTION_SCOPE" ] }, "triggersTriggerSubscription": { "description": "A subscription of one connected account, or of a whole connection, to one trigger.", "type": "object", "properties": { "account_health": { "description": "How the subscribed account stands for this trigger. AWAITING_CONFIRMATION means Scalekit cannot route this trigger's events to the account yet, so the subscription will not fire until the account's user reconnects it. Absent for connection-scoped subscriptions.", "$ref": "#/components/schemas/triggersAccountHealthState", "examples": [ "READY" ] }, "config": { "description": "The subscription's filter values, keyed by the trigger's config_fields keys. Keys are returned exactly as stored; send them back without changing their case.", "type": "object", "additionalProperties": { "type": "string" }, "examples": [ { "channel": "C0123456789" } ] }, "connected_account_id": { "description": "ID of the subscribed connected account. Empty for a connection-scoped subscription.", "type": "string", "examples": [ "ca_123456789012345" ] }, "connected_account_identifier": { "description": "The identifier the connected account was created with, such as your app's user ID or the user's email address, so a client can label the subscription without fetching every account separately. Empty for a connection-scoped subscription, and empty when the account has no identifier recorded — fall back to connected_account_id rather than showing a blank.", "type": "string", "examples": [ "user_123" ] }, "connection_id": { "description": "ID of the connection the subscription belongs to.", "type": "string", "examples": [ "conn_123456789012345" ] }, "created_at": { "description": "When the subscription was created. Returned so a list can be ordered or explained by age without a second lookup.", "type": "string", "format": "date-time" }, "delivery_scope": { "description": "Whether this subscription receives one event per connected account or one event for the whole connection. A connection-scoped subscription carries no connected_account_id — the connection is the only recipient.", "$ref": "#/components/schemas/triggersTriggerDeliveryScope", "examples": [ "ACCOUNT" ] }, "effective_interval_seconds": { "description": "The polling interval, in seconds, the subscription actually runs at. Larger than requested_interval_seconds when the environment's polling budget is shared across many polled subscriptions; the subscription's status is then THROTTLED. Zero for a webhook trigger.", "type": "integer", "format": "int32", "examples": [ 60 ] }, "id": { "description": "Unique identifier of the trigger subscription.", "type": "string", "examples": [ "trgs_123456789012345" ] }, "poll_state": { "description": "How a POLL subscription's feed is doing: when it last ran, why the last run failed, and whether polling is held off. Absent for a WEBHOOK subscription, which is never polled.", "$ref": "#/components/schemas/triggersTriggerPollState" }, "provider": { "description": "The provider the trigger belongs to.", "type": "string", "examples": [ "slack" ] }, "requested_interval_seconds": { "description": "The polling interval, in seconds, the subscription asked for, or the trigger's default when it did not set one. Returned next to effective_interval_seconds so a subscription running slower than requested is visible. Zero for a webhook trigger.", "type": "integer", "format": "int32", "examples": [ 60 ] }, "status": { "description": "Whether the subscription is delivering. ACTIVE — delivering. THROTTLED — delivering, but polling slower than requested; compare requested_interval_seconds with effective_interval_seconds. PAUSED — stopped by the customer. PAUSED_CREDENTIAL — stopped because the account's credential no longer works.", "$ref": "#/components/schemas/triggersTriggerSubscriptionStatus", "examples": [ "ACTIVE" ] }, "trigger_name": { "description": "Name of the subscribed trigger, as returned by ListAvailableTriggers.", "type": "string", "examples": [ "slack_message_posted" ] } } }, "triggersTriggerSubscriptionStatus": { "description": "Why a subscription is or is not currently delivering.\n\n - ACTIVE: Delivering. For a polled trigger, at the requested interval.\n - THROTTLED: Running slower than requested, not stopped. Still delivering.\n - PAUSED: Stopped by the customer.\n - PAUSED_CREDENTIAL: Stopped because the account's credential no longer works.\nDistinct from PAUSED so the two have distinguishable explanations for missing events.", "type": "string", "enum": [ "ACTIVE", "THROTTLED", "PAUSED", "PAUSED_CREDENTIAL" ] }, "triggersTriggerUsageBucket": { "description": "The size of each entry in a trigger usage response.\n\n - TRIGGER_USAGE_BUCKET_DAY: One entry per UTC calendar day, in days. Returned\nfor period 7d and 30d.\n - TRIGGER_USAGE_BUCKET_HOUR: One entry per UTC clock hour, in hours. Returned\nfor period 24h.", "type": "string", "enum": [ "TRIGGER_USAGE_BUCKET_DAY", "TRIGGER_USAGE_BUCKET_HOUR" ] }, "triggersTriggerUsageDay": { "description": "Trigger deliveries metered for an environment on one UTC calendar day.", "type": "object", "properties": { "date": { "description": "The UTC calendar date, as YYYY-MM-DD.", "type": "string", "examples": [ "2026-10-08" ] }, "units": { "description": "Trigger deliveries metered for this environment on this day: one for each trigger event sent to one receiving endpoint. Always greater than zero; a day with none is left out of the response.", "type": "string", "format": "int64", "examples": [ 447 ] } } }, "triggersTriggerUsageHour": { "description": "Trigger deliveries metered for an environment in one UTC clock hour.", "type": "object", "properties": { "start": { "description": "The start of the UTC clock hour, as an RFC 3339 timestamp in UTC (`Z`) with zero minutes and seconds. The hour runs from `start` up to, not including, `start` plus one hour.", "type": "string", "examples": [ "2026-10-14T17:00:00Z" ] }, "units": { "description": "Trigger deliveries metered for this environment in this hour: one for each trigger event sent to one receiving endpoint. Always greater than zero; an hour with none is left out of the response.", "type": "string", "format": "int64", "examples": [ 38 ] } } } }, "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 } ] } }