{ "info": { "description": "# Overview\n\nThe Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS.\nAll 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\nScalekit operates two separate environments: Development and Production. Resources cannot be moved between environments.\n\n## Quickstart\n\nThe Scalekit API uses OAuth 2.0 Client Credentials for authentication.\n\nCopy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.\n\n```sh\nSCALEKIT_ENVIRONMENT_URL=''\nSCALEKIT_CLIENT_ID=''\nSCALEKIT_CLIENT_SECRET=''\n```\n\nGetting an access token\n\n1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)\n2. Request an access token:\n\n```sh\ncurl https:///oauth/token \\\n -X POST \\\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\n3. Use the access token in API requests:\n\n```sh\ncurl https:///api/v1/organizations \\\n -H 'Content-Type: application/json' \\\n -H 'Authorization: Bearer {access_token}'\n```\n\nThe response includes an access token:\n\n```json\n{\n\t\"access_token\": \"eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...\",\n\t\"token_type\": \"Bearer\",\n\t\"expires_in\": 86399,\n\t\"scope\": \"openid\"\n}\n```\n\n## SDKs\n\nScalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates.\n\n### Node.js\n\n```sh\nnpm install @scalekit-sdk/node\n```\n\nCreate a new Scalekit client instance after initializing the environment variables\n\n```js\nimport { Scalekit } from \"@scalekit-sdk/node\";\n\nexport let scalekit = new Scalekit(\n\tprocess.env.SCALEKIT_ENVIRONMENT_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\n```\n\n[See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases)\n\n### Python\n\n```sh\npip install scalekit-sdk-python\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```py\nfrom scalekit import ScalekitClient\nimport os\n\nscalekit_client = ScalekitClient(\n os.environ.get('SCALEKIT_ENVIRONMENT_URL'),\n os.environ.get('SCALEKIT_CLIENT_ID'),\n os.environ.get('SCALEKIT_CLIENT_SECRET')\n)\n```\n\n[See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases)\n\n### Go\n\n```sh\ngo get -u github.com/scalekit-inc/scalekit-sdk-go\n```\n\nCreate a new Scalekit client instance after initializing the environment variables.\n\n```go\npackage main\n\nimport (\n \"os\"\n \"github.com/scalekit-inc/scalekit-sdk-go\"\n)\n\nscalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENVIRONMENT_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\n```\n\n[See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases)\n\n### Java\n\n```gradle\n/* Gradle users - add the following to your dependencies in build file */\nimplementation \"com.scalekit:scalekit-sdk-java:2.0.11\"\n```\n\n```xml\n\n\n com.scalekit\n scalekit-sdk-java\n 2.0.11\n\n```\n\n[See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases)\n\n### Error handling\n\nThe API uses standard HTTP status codes:\n\n| Code | Description |\n| ----------- | -------------------- |\n| 200/201 | Success |\n| 400 | Invalid request |\n| 401 | Authentication error |\n| 404 | Resource not found |\n| 429 | Rate limit exceeded |\n| 500/501/504 | Server error |\n\nError responses include detailed information:\n\n```json\n{\n\t\"code\": 16,\n\t\"message\": \"Token empty\",\n\t\"details\": [\n\t\t{\n\t\t\t\"@type\": \"type.googleapis.com/scalekit.v1.errdetails.ErrorInfo\",\n\t\t\t\"error_code\": \"UNAUTHENTICATED\"\n\t\t}\n\t]\n}\n```\n", "title": "Scalekit APIs", "contact": { "name": "Scalekit Inc", "url": "https://scalekit.com", "email": "support@scalekit.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" }, "version": "1.0.0", "x-scalar-sdk-installation": [ { "lang": "shell", "description": "Set up OAuth 2.0 Client Credentials authentication to access Scalekit APIs. Includes credential configuration, token exchange, and authenticated API request examples.", "source": "\n# 1. Obtain API Credentials\n# Get your credentials from the Scalekit dashboard\nexport SCALEKIT_ENVIRONMENT_URL=\"https://your-org.scalekit.dev\" # Your Scalekit environment URL\nexport SCALEKIT_CLIENT_ID=\"your_client_id\" # Your client ID\nexport SCALEKIT_CLIENT_SECRET=\"your_client_secret\" # Your client secret\n\n# 2. Exchange client credentials an OAuth 2.0 access token\nTOKEN_RESPONSE=$(curl -s -X POST \"${SCALEKIT_ENVIRONMENT_URL}/oauth/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"client_id=${SCALEKIT_CLIENT_ID}\" \\\n -d \"client_secret=${SCALEKIT_CLIENT_SECRET}\" \\\n -d \"grant_type=client_credentials\")\n\n# 3. Make Authenticated API Requests\ncurl -X GET \"${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n -H \"Accept: application/json\"\n" } ] }, "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. Connector identifier such as 'notion', 'slack', 'google', etc. Alphanumeric with spaces, hyphens, underscores, and colons 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 per page. Must be between 0 and 100. Default is typically 10.", "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" } ], "responses": { "200": { "description": "Successfully retrieved the list of connected accounts with their authentication details and status", "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": {} } } } } }, "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 new connected account with OAuth tokens or API credentials for third-party service integration. Supply authorization details including access tokens, refresh tokens, scopes, and optional API configuration. The account can be scoped to an organization or user. Returns the created account with its unique identifier and authentication status.", "tags": ["Connected Accounts"], "summary": "Create a connected account", "operationId": "ConnectedAccountService_CreateConnectedAccount", "responses": { "201": { "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", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "409": { "description": "Conflict - connected account with the same identifier already exists", "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 details", "operationId": "ConnectedAccountService_GetConnectedAccountAuth", "parameters": [ { "schema": { "type": "string" }, "description": "Organization ID for the connector", "name": "organization_id", "in": "query" }, { "schema": { "type": "string" }, "description": "User ID for the connector", "name": "user_id", "in": "query" }, { "schema": { "type": "string" }, "description": "Connector identifier", "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/magic_link": { "post": { "description": "Creates a time-limited magic link for connecting or re-authorizing a third-party account. The link directs users to the OAuth authorization flow for the specified connector. Returns the generated link URL and expiration timestamp. Links typically expire after a short duration for security.", "tags": ["Connected Accounts"], "summary": "Generate authentication magic link", "operationId": "ConnectedAccountService_GetMagicLinkForConnectedAccount", "responses": { "200": { "description": "Magic link generated successfully with authorization URL and expiry time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/connected_accountsGetMagicLinkForConnectedAccountResponse" } } } }, "400": { "description": "Invalid request - missing required parameters or invalid connector", "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/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": "Permanently removes a connected account and revokes all associated authentication credentials. Identify the account by ID, or by combination of organization/user, connector, and identifier. This action cannot be undone. All OAuth tokens and API keys for this account will be invalidated.", "tags": ["Connected Accounts"], "summary": "Delete a connected account", "operationId": "ConnectedAccountService_DeleteConnectedAccount", "responses": { "200": { "description": "Connected account deleted successfully and all credentials revoked", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid request - malformed parameters 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_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/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/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": ["Connected Accounts"], "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 - occurs when tool name is missing, parameters are malformed, or tool definition validation fails", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Authentication required - missing or invalid access token", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Tool or connected account not found - occurs when the specified tool name or connected account does not exist", "content": { "application/json": { "schema": {} } } }, "500": { "description": "Tool execution failed - occurs when the external service returns an error or the tool encounters a runtime exception", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/toolsExecuteToolRequest" } } }, "required": true } } }, "/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/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": "string" }, "description": "External system identifier from connected directories. Must be unique across the system", "name": "external_id", "in": "query" }, { "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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "import { ScalekitClient } from \"@scalekit-sdk/node\";\nconst scalekit = new ScalekitClient(\n\tprocess.env.SCALEKIT_ENV_URL,\n\tprocess.env.SCALEKIT_CLIENT_ID,\n\tprocess.env.SCALEKIT_CLIENT_SECRET\n);\nawait scalekit.user.createMembership(\"org_123\", \"usr_123\", {\n\troles: [\"admin\"],\n\tmetadata: {\n\t\tdepartment: \"engineering\",\n\t\tlocation: \"nyc-office\",\n\t},\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": "func main() {\n scalekitClient := scalekit.NewScalekitClient(\n os.Getenv(\"SCALEKIT_ENV_URL\"),\n os.Getenv(\"SCALEKIT_CLIENT_ID\"),\n os.Getenv(\"SCALEKIT_CLIENT_SECRET\"),\n )\n membership := &usersv1.CreateMembership{\n Roles: []*usersv1.Role{{Name: \"admin\"}},\n Metadata: map[string]string{\n \"department\": \"engineering\",\n \"location\": \"nyc-office\",\n },\n }\n resp, \n err := scalekitClient.User().CreateMembership(\n context.Background(), \"org_123\", \n \"usr_123\", membership, false)\n if err != nil {\n panic(err)\n }\n}" }, { "label": "Java SDK", "lang": "java", "source": "import com.scalekit.ScalekitClient;\nimport com.scalekit.api.UserClient;\nimport com.scalekit.grpc.scalekit.v1.users.*;\nScalekitClient scalekitClient = new ScalekitClient(\n System.getenv(\"SCALEKIT_ENV_URL\"),\n System.getenv(\"SCALEKIT_CLIENT_ID\"),\n System.getenv(\"SCALEKIT_CLIENT_SECRET\")\n);\nUserClient users = scalekitClient.users();\nCreateMembershipRequest membershipReq = CreateMemb\n ershipRequest.newBuilder()\n .setMembership(\n CreateMembership.newBuilder()\n .addRoles(Role.newBuilder(\n ).setName(\"admin\").build())\n .putMetadata(\"department\", \"engineering\")\n .putMetadata(\"location\", \"nyc-office\")\n .build())\n .build();\nCreateMembershipResponse res = users.\n createMembership(\"org_123\", \"usr_123\", \n membershipReq);" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Membership details to create. Required fields must be provided.", "$ref": "#/components/schemas/v1usersCreateMembership" } } }, "required": true } }, "delete": { "description": "Removes a user from an organization by user ID or external ID. If the user has no memberships left and cascade is true, the user is also deleted. 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 }, { "schema": { "type": "string" }, "description": "External system identifier from connected directories. Must match existing records", "name": "external_id", "in": "query" } ], "responses": { "200": { "description": "User successfully marked for deletion. No content returned", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Python SDK", "lang": "python", "source": "response = scalekit_client.users.delete_membership(\n organization_id=org_id,user_id=user_id\n)" } ] }, "patch": { "description": "Updates a user's membership details within an organization by user ID or external 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 }, { "schema": { "type": "string" }, "description": "Your application's unique identifier for this user.", "name": "external_id", "in": "query" } ], "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\tpageSize: 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.ListOrganizations(\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": "" } ], "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const organization = await scalekit.organization.createOrganization(name, {\n\n\texternalId: \"externalId\",\n\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);" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Required parameters for creating a new organization", "$ref": "#/components/schemas/v1organizationsCreateOrganization" } } }, "description": "Organization details", "required": true } } }, "/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 that uniquely references an organization", "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 scalekit = new ScalekitClient(\n ,\n ,\n \n);\n\nconst organization = await scalekit.organization.getOrganization(organization_id);" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client = ScalekitClient(\n ,\n ,\n \n)\n\norganization = scalekit_client.organization.get_organization(\n organization_id\n)" }, { "label": "Go SDK", "lang": "go", "source": "scalekitClient := scalekit.NewScalekitClient(\n ,\n ,\n \n)\n\norganization, 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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Organization Parameters to be updated", "$ref": "#/components/schemas/v1organizationsUpdateOrganization" } } }, "required": true } } }, "/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://scalekit.com/portal/lnk_123?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": {} } } } }, "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));" } ], "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": "directory_sync" } ] } ] } } }, "required": true } } }, "/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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Organization role details", "$ref": "#/components/schemas/v1rolesCreateOrganizationRole" } } }, "required": true } } }, "/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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Organization role details", "$ref": "#/components/schemas/v1rolesUpdateRole" } } }, "required": true } }, "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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesServiceUpdateDefaultOrganizationRolesBody" } } }, "required": true } } }, "/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": "Python SDK", "lang": "python", "source": "# List clients for a specific organization\norg_id = 'SCALEKIT_ORGANIZATION_ID'\n\n# Retrieve all clients with default pagination\nresponse = scalekit_client.m2m_client.list_organization_clients(\n organization_id=org_id,\n page_size=30\n)\n\n# Access the clients list\nclients = response.clients\nfor client in clients:\n print(f\"Client ID: {scalekit_client.id}, Name: {scalekit_client.name}\")" } ] }, "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" } } } } }, "x-codeSamples": [ { "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\nto 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=\"SCALEKIT_ORGANIZATION_ID\",\n m2m_client=m2m_client\n)" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Details of the client to be created", "$ref": "#/components/schemas/clientsOrganizationClient" } } }, "required": true } } }, "/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": "Python SDK", "lang": "python", "source": "# Get client ID from environment variables\norg_id = 'SCALEKIT_ORGANIZATION_ID'\nclient_id = os.environ['M2M_CLIENT_ID']\n\n# Fetch client details for the specified organization\nresponse = scalekit_client.m2m_client.get_organization_client(\n organization_id=org_id,\n client_id=client_id\n)" } ] }, "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": "Python SDK", "lang": "python", "source": "# Get client ID from environment variables\norg_id = ''\nclient_id = os.environ['M2M_CLIENT_ID']\n\n# Delete the specified client from the organization\nresponse = scalekit_client.m2m_client.delete_organization_client(\n organization_id=org_id,\n client_id=client_id\n)" } ] }, "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" } } } } }, "x-codeSamples": [ { "label": "Python SDK", "lang": "python", "source": "from scalekit.v1.clients.clients_pb2 import OrganizationClient\n\norg_id = ''\nclient_id = os.environ['M2M_CLIENT_ID']\n\nupdate_m2m_client = OrganizationClient(\n description=\"Service account for GitHub Actions to deploy applications\nto 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)" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Updated details for the client", "$ref": "#/components/schemas/clientsOrganizationClient" } } }, "required": true } } }, "/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": "Python SDK", "lang": "python", "source": "# Get client ID from environment variables\norg_id = 'SCALEKIT_ORGANIZATION_ID'\nclient_id = os.environ['M2M_CLIENT_ID']\n\n# Add a new secret to the specified client\nresponse = scalekit_client.m2m_client.add_organization_client_secret(\n organization_id=org_id,\n client_id=client_id\n)\n\n# Extract the secret ID from the response\nsecret_id = response[0].secret.id" } ] } }, "/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": "Python SDK", "lang": "python", "source": "# Get client and secret IDs from environment variables\norg_id = ''\nclient_id = os.environ['M2M_CLIENT_ID']\nsecret_id = os.environ['M2M_SECRET_ID']\n\n# Remove the specified secret from the client\nresponse = scalekit_client.m2m_client.remove_organization_client_secret(\n organization_id=org_id,\n client_id=client_id,\n secret_id=secret_id\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(\n organizationId,\n connectionId\n);" }, { "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(\n '',\n ''\n);" }, { "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(\n organizationId,\n directoryId\n);" }, { "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(\n '',\n ''\n);" }, { "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\tdomainType: \"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" } } } } }, "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\n\t// Domain type: controls user authentication and email validation\n\n\tdomainType: \"ORGANIZATION_DOMAIN\",\n\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);" } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Domain configuration including the domain name and type.", "$ref": "#/components/schemas/v1domainsCreateDomain" } } }, "required": true } } }, "/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}/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.\n listOrganizationUsers(\"org_123\", {\n\tpageSize: 50,\n});\nconsole.log(response.users);" }, { "label": "Python SDK", "lang": "python", "source": "resp, _ = scalekit_client.users.list_users(organization_id=\"org_123\", page_size=50)" }, { "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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const {\n user } = await scalekit.user.\n createUserAndMembership(\"org_123\", {\n\temail: \"user@example.com\",\n\texternalId: \"ext_12345a67b89c\",\n\tmetadata: { department: \"engineering\", \n\t location: \"nyc-office\" },\n\tuserProfile: {\n\t\tfirstName: \"John\",\n\t\tlastName: \"Doe\",\n\t},\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());" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersCreateUser" } } }, "required": true } } }, "/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", "tags": ["Organizations"], "summary": "Get organization details by external Id", "operationId": "OrganizationService_GetOrganizationByExternalId", "parameters": [ { "schema": { "type": "string" }, "description": "Unique identifier that links an Organization Object to your app's tenant, stored as an External ID", "name": "external_id", "in": "path", "required": true }, { "schema": { "type": "string" }, "description": "Unique scalekit-generated identifier that uniquely references an organization", "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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { authRequestId } = sendResponse;\nconst resendResponse = await scalekit.passwordless.resendPasswordlessEmail(\n\n\tauthRequestId\n\n);" }, { "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 = passwordlessClient.resendPasswordlessEmail(authRequestId);" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessResendPasswordlessRequest" } } }, "required": true } } }, "/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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const response = await scalekit.passwordless.sendPasswordlessEmail(\n\t\"john.doe@example.com\",\n\t{\n\t\ttemplate: \"SIGNIN\",\n\t\texpiresIn: 100,\n\t\tmagiclinkAuthUri: \"https://www.google.com\",\n\t\ttemplateVariables: {\n\t\t\temployeeID: \"EMP523\",\n\t\t\tteamName: \"Alpha Team\",\n\t\t\tsupportEmail: \"support@yourcompany.com\",\n\t\t},\n\t}\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://www.google.com\",\n template_variables={\n \"employeeID\": \"EMP523\",\n \"teamName\": \"Alpha Team\",\n \"supportEmail\": \"support@yourcompany.com\",\n },\n)\n\n# Extract auth request ID from response\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://www.google.com\",\n TemplateVariables: map[string]string{\n \"employeeID\": \"EMP523\",\n \"teamName\": \"Alpha Team\",\n \"supportEmail\": \"support@yourcompany.com\",\n },\n },\n)\n\nif err != nil {\n // Handle error\n return\n}\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://www.example.com\");\noptions.setTemplateVariables(templateVariables);\n\nSendPasswordlessResponse response = passwordlessClient.sendPasswordlessEmail(\n \"john.doe@example.com\",\n options\n);\n\nString authRequestId = response.getAuthRequestId();" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessSendPasswordlessRequest" } } }, "required": true } } }, "/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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { authRequestId } = sendResponse;\nconst verifyResponse = await scalekit.passwordless.verifyPasswordlessEmail(\n\n\t// Verification Code (OTP)\n\n\t{ code: \"123456\" },\n\n\t// Magic Link Token\n\n\t{ linkToken: link_token },\n\n\tauthRequestId\n\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 = passwordlessClient.verifyPasswordlessEmail(verifyOptions);\n\n// User verified successfully\nString userEmail = verifyResponse.getEmail();\n\n// Verify with magic link token\nVerifyPasswordlessOptions verifyOptions = new VerifyPasswordlessOptions();\nverifyOptions.setLinkToken(linkToken); // Magic link token\n\nVerifyPasswordLessResponse verifyResponse = passwordlessClient.verifyPasswordlessEmail(verifyOptions);\n\n// User verified successfully\nString userEmail = verifyResponse.getEmail();" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/passwordlessVerifyPasswordLessRequest" } } }, "required": true } } }, "/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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1rolesCreatePermission" } } }, "required": true } } }, "/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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/v1rolesCreatePermission" } } }, "required": true } }, "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" } } } } }, "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);" } ], "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 } } }, "/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" } } } } }, "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);" } ], "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 } }, "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}/base": { "delete": { "description": "Removes the base role inheritance relationship for a specified role, effectively eliminating all inherited permissions from the base role. Use this endpoint when you want to break the hierarchical relationship between roles and remove inherited permissions. The role will retain only its directly assigned permissions after this operation. This action cannot be undone, so ensure the role has sufficient direct permissions before removing inheritance. Returns no content on successful removal of the base relationship.", "tags": ["Roles"], "summary": "Delete role inheritance relationship", "operationId": "RolesService_DeleteRoleBase", "parameters": [ { "schema": { "type": "string" }, "description": "Unique name identifier of the role whose base inheritance relationship should be removed. Must be alphanumeric with underscores, 1-64 characters.", "name": "role_name", "in": "path", "required": true } ], "responses": { "200": { "description": "Base role inheritance relationship successfully removed. The role now has only its directly assigned permissions.", "content": { "application/json": { "schema": {} } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.role.deleteRoleBase(\"senior_editor\");" }, { "label": "Python SDK", "lang": "python", "source": "scalekit_client.roles.delete_role_base(role_name=\"senior_editor\")" }, { "label": "Go SDK", "lang": "go", "source": "err := scalekitClient.Role().DeleteRoleBase(ctx, \"senior_editor\")\nif err != nil {\n // handle error\n}" }, { "label": "Java SDK", "lang": "java", "source": "scalekitClient.roles().deleteRoleBase(\"senior_editor\");" } ] } }, "/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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolesServiceAddPermissionsToRoleBody" } } }, "required": true } } }, "/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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const { permissions } = await scalekit.permission.listEffectiveRolePermissions(\"senior_editor\");" }, { "label": "Python SDK", "lang": "python", "source": "response = scalekit_client.permissions.list_effective_role_permissions(role_name=\"senior_editor\")\npermissions = response.permissions" }, { "label": "Go SDK", "lang": "go", "source": "resp, err := scalekitClient.Permission().ListEffectiveRolePermissions(ctx, \"senior_editor\")\nif err != nil {\n // handle error\n}\npermissions := resp.Permissions" }, { "label": "Java SDK", "lang": "java", "source": "ListEffectiveRolePermissionsResponse response = scalekitClient.permissions().listEffectiveRolePermissions(\"senior_editor\");\nList permissions = response.getPermissionsList();" } ] } }, "/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" } } } } }, "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);" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rolesUpdateDefaultRolesRequest" } } }, "required": true } } }, "/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/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(\n { pageSize: 100 });" }, { "label": "Python SDK", "lang": "python", "source": "# pass empty org to fetch all users in environment\nresp,_ = scalekit_client.users.list_users(organization_id=\"\", 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.\n newBuilder().setPageSize(100).build();\nListUsersResponse allUsers = users.listUsers(lur);" } ] } }, "/api/v1/users/{id}": { "get": { "description": "Retrieves all details for a user by system-generated user ID or external 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 }, { "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": "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 }, { "schema": { "type": "string" }, "description": "External system identifier from connected directories. Must match existing records", "name": "external_id", "in": "query" } ], "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(organization_id=\"org_123\", \n user_id=\"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": "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 }, { "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": "User updated successfully. Returns the modified user object with updated timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usersUpdateUserResponse" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "await scalekit.user.updateUser(\"usr_123\", {\n\tuserProfile: {\n\t\tfirstName: \"John\",\n\t\tlastName: \"Smith\",\n\t},\n\tmetadata: {\n\t\tdepartment: \"sales\",\n\t},\n});" }, { "label": "Python SDK", "lang": "python", "source": "import os\nfrom scalekit import ScalekitClient\nfrom scalekit.v1.users.users_pb2 import UpdateUser\nfrom scalekit.v1.commons.commons_pb2 import UserProfile\nscalekit_client = ScalekitClient(\n env_url=os.getenv(\"SCALEKIT_ENV_URL\"),\n client_id=os.getenv(\"SCALEKIT_CLIENT_ID\"),\n client_secret=os.getenv(\"SCALEKIT_CLIENT_SECRET\"),\n)\nupdate_user = UpdateUser(\n user_profile=UserProfile(\n first_name=\"John\",\n last_name=\"Smith\"\n ),\n metadata={\"department\": \"sales\"}\n)\nscalekit_client.users.update_user(organization_id=\"org_123\", \n user=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.\n newBuilder().setUser(upd).build();\nusers.updateUser(\"usr_123\", updReq);" } ], "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/{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: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" } } } } }, "x-codeSamples": [ { "label": "Node.js SDK", "lang": "javascript", "source": "const res = await scalekit.webauthn.updateCredential(\n \"wac_123\",\n \"Work Laptop Passkey\"\n);" }, { "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\");" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnServiceUpdateCredentialBody" } } }, "required": true } } } }, "tags": [ { "description": "Organization represents a customer or a tenant of your product. This is the top level entity and all resources are mapped to this Organization object. Each organization is uniquely identified by `organization_id`.\n\n\n", "name": "Organizations" }, { "description": "Permission management for defining and controlling access to system resources. Create, retrieve, update, and delete granular permissions that represent specific actions users can perform. Permissions are the building blocks of role-based access control (RBAC) and can be assigned to roles to grant users the ability to perform specific operations. Use this service to define custom permissions for your application's unique access control requirements.", "name": "Permissions" }, { "description": "Comprehensive user management operations including user lifecycle, organization memberships, and invitation workflows. This service provides endpoints for creating, retrieving, updating, and deleting user accounts across your Scalekit environment. It supports both individual user operations and bulk operations for user administration, including user search, pagination, and metadata management. The service also handles user invitations and organization membership management.", "name": "Users" }, { "description": "Manage enterprise connections for your Scalekit environment. This service provides endpoints for retrieving, and updating connections.", "name": "Connections" }, { "description": "Directory management for viewing and controlling external identity provider connections in your Scalekit environment. This service provides endpoints for retrieving directory information, listing directories and their contents, and enabling or disabling directory synchronization.", "name": "Directory" }, { "description": "Role-based access control (RBAC) for defining and managing permissions in an environment. Create and update custom roles with explicit permissions, model role hierarchies through inheritance, view dependent roles, manage role-permission assignments, and list roles and permissions. Also provides a utility to count users assigned to a role.", "name": "Roles" }, { "description": "Comprehensive session management for user authentication and authorization. This service provides endpoints for retrieving session details, managing user sessions across devices, revoking individual sessions, and terminating all active sessions for a user. It supports session auditing, device tracking, and security monitoring with detailed session metadata including device information, IP geolocation, and activity timestamps.", "name": "Sessions" }, { "description": "Manage organization-level domains. Scalekit supports two domain types:\n\n- ORGANIZATION_DOMAIN: Used for SSO domain discovery. When a user signs in with a matching email domain, Scalekit routes them to the organization’s SSO provider and enforces SSO.\n- ALLOWED_EMAIL_DOMAIN: Used to mark trusted email domains for an organization. When a user signs in or signs up with a matching domain, Scalekit suggests the organization in the organization switcher (authentication-method agnostic).\n", "name": "Domains" }, { "description": "Endpoints for managing API client applications. API clients enable secure, automated interactions between software systems without human intervention. Each client is uniquely identified by a `client_id` and can be configured with authentication settings, redirect URIs, and security parameters. Use these endpoints to create, manage, and configure API clients for your API clients.", "name": "API Auth", "externalDocs": { "url": "https://docs.scalekit.com/m2m/overview" } }, { "description": "Endpoints for sending and verifying passwordless authentication emails. These APIs allow users to authenticate without passwords by receiving a verification code or magic link in their email.", "name": "Magic link & OTP" }, { "description": "Endpoints for passkey-based authentication using WebAuthn/FIDO2 standards.", "name": "Passkeys" }, { "description": "Manage connected accounts for third-party integrations and OAuth connections. Connected accounts represent authenticated access to external services like Google, Notion, Slack, and other applications.", "name": "Connected Accounts" } ], "externalDocs": { "description": "Scalekit Docs", "url": "https://docs.scalekit.com/" }, "openapi": "3.1.1", "servers": [ { "url": "https://$SCALEKIT_ENVIRONMENT_URL" } ], "components": { "schemas": { "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" } } }, "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"] } } }, "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": { "oauth_token": { "title": "OAuth 2.0 credentials", "$ref": "#/components/schemas/connected_accountsOauthToken" }, "static_auth": { "title": "Static authentication credentials", "$ref": "#/components/schemas/connected_accountsStaticAuth" } } }, "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": "Sensitive authentication credentials including access tokens, refresh tokens, and scopes. Contains either OAuth tokens or static auth details.", "$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"] }, "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": "OAuth provider name (e.g., 'google', 'microsoft', 'github'). Identifies which authentication service manages this connection.", "type": "string", "examples": ["google"] }, "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"] }, "last_used_at": { "description": "Last usage timestamp.", "type": "string", "format": "date-time", "examples": ["2024-03-20T14:30:00Z"] }, "provider": { "description": "OAuth provider name (e.g., 'google', 'microsoft').", "type": "string", "examples": ["google"] }, "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", "type": "string", "title": "Status of a connected account indicating its current state", "enum": ["ACTIVE", "EXPIRED", "PENDING_AUTH", "PENDING_VERIFICATION"] }, "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)", "type": "string", "title": "Type of authentication mechanism used for the connected account", "enum": ["OAUTH", "API_KEY", "BASIC_AUTH", "BEARER_TOKEN", "CUSTOM", "BASIC"] }, "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", "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": "Organization ID for the connector", "type": "string", "examples": ["org_121312434123312"] }, "user_id": { "description": "User ID for the connector", "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", "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": "Organization ID for the connector", "type": "string", "examples": ["org_121312434123312"] }, "user_id": { "description": "User ID for the connector", "type": "string", "examples": ["user_121312434123312"] } } }, "connected_accountsDeleteConnectedAccountResponse": { "type": "object" }, "connected_accountsGetConnectedAccountByIdentifierResponse": { "type": "object", "properties": { "connected_account": { "description": "The connected account with complete details including sensitive authorization credentials (access tokens, refresh tokens, scopes). Handle with appropriate access controls.", "$ref": "#/components/schemas/connected_accountsConnectedAccount" } } }, "connected_accountsGetMagicLinkForConnectedAccountRequest": { "type": "object", "properties": { "connector": { "description": "Connector identifier", "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": "Organization ID for the connector", "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": "User ID for the connector", "type": "string", "examples": ["user_121312434123312"] }, "user_verify_url": { "description": "B2B app's user verify redirect URL", "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": "Authentication link for the connector", "type": "string", "examples": ["https://notion.com/oauth/authorize?client_id=..."] } } }, "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_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", "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": "Organization ID for the connector", "type": "string", "examples": ["org_121312434123312"] }, "user_id": { "description": "User ID for the connector", "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"] }, "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] }, "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" }, "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. Can be OIDC (OpenID Connect), SAML, OAUTH, or MAGIC_LINK.", "$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" ] }, "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" } } }, "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"] }, "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"] }, "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"] }, "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_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"] }, "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" ] }, "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"] } } }, "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] } } }, "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" } } } }, "organizationsCreateOrganizationResponse": { "type": "object", "properties": { "organization": { "description": "The newly created organization containing its ID, settings, and metadata", "$ref": "#/components/schemas/organizationsOrganization" } } }, "organizationsFeature": { "description": "- dir_sync: Enables directory synchronization configuration in the portal\n - sso: Enables Single Sign-On (SSO) configuration in the portal", "type": "string", "title": "Feature represents the available features that can be enabled for an organization's portal link", "enum": ["dir_sync", "sso"] }, "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" } } }, "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://scalekit.com/portal/lnk_123123123123123"] } } }, "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"] }, "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" }, "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"] } } }, "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": "directory_sync" } ] ] } }, "examples": [ { "features": [ { "enabled": true, "name": "sso" }, { "enabled": false, "name": "directory_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), \"directory_sync\" (Directory Synchronization)", "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] } } }, "organizationsUpdateOrganizationResponse": { "type": "object", "properties": { "organization": { "description": "Updated organization details", "$ref": "#/components/schemas/organizationsOrganization" } } }, "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"] } } }, "protobufNullValue": { "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`.", "type": "string" }, "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" } } }, "rolesPermissionType": { "type": "string", "enum": ["SCALEKIT", "ENVIRONMENT"] }, "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] } } }, "sessionsUserSessionFilter": { "type": "object", "properties": { "end_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.", "type": "string", "format": "date-time", "examples": ["2025-12-31T23:59:59Z"] }, "start_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.", "type": "string", "format": "date-time", "examples": ["2025-01-01T00:00:00Z"] }, "status": { "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).", "type": "array", "items": { "type": "string" }, "examples": [["active"]] } } }, "toolsExecuteToolRequest": { "type": "object", "properties": { "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'). 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": "Free-flowing JSON parameters for the tool execution", "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"] } } }, "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"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "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"] }, "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" } ] } } }, "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", "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 organization, 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"] } } }, "ScalekitEvent": { "type": "object", "required": ["spec_version", "id", "type", "occurred_at", "environment_id", "object"], "properties": { "spec_version": { "type": "string", "example": "1", "description": "The webhook specification version", "pattern": "^[0-9]+$" }, "id": { "type": "string", "pattern": "^evt_", "example": "evt_1234567890abcdef", "description": "Unique identifier for the webhook event (must be prefixed with \"evt_\")", "minLength": 1, "maxLength": 32 }, "type": { "type": "string", "example": "organization.created", "description": "The event type", "enum": [ "organization.created", "organization.updated", "organization.deleted", "organization.sso_created", "organization.sso_deleted", "organization.sso_enabled", "organization.sso_disabled", "user.signup", "user.login", "user.logout", "user.organization_invitation", "user.organization_membership_created", "user.organization_membership_updated", "user.organization_membership_deleted", "organization.directory.user_created", "organization.directory.user_updated", "organization.directory.user_deleted", "organization.directory.group_created", "organization.directory.group_updated", "organization.directory.group_deleted", "organization.directory_enabled", "organization.directory_disabled", "role.created", "role.updated", "role.deleted", "permission.created", "permission.updated", "permission.deleted" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the event occurred (ISO 8601 format)", "example": "2024-01-01T00:00:00Z" }, "environment_id": { "type": "string", "pattern": "^env_", "example": "env_1234567890abcdef", "description": "The environment ID where the event occurred", "minLength": 1, "maxLength": 32 }, "organization_id": { "type": "string", "pattern": "^org_", "example": "org_1234567890abcdef", "description": "The organization ID (if applicable)", "minLength": 1, "maxLength": 32 }, "object": { "type": "string", "description": "The type of object that triggered the webhook", "enum": [ "Organization", "Connection", "Role", "Directory", "DirectoryUser", "DirectoryGroup", "Permission", "OrgMembership", "User" ], "example": "Organization" }, "data": { "type": "object", "description": "The event payload (structure varies by event type)", "additionalProperties": true, "example": { "id": "org_1234567890abcdef", "name": "Example Organization", "created_at": "2024-01-01T00:00:00Z" } }, "display_name": { "type": "string", "description": "Human-readable display name for the event", "example": "Organization Created", "minLength": 1, "maxLength": 200 } } } }, "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", "security": [ { "oauth2": [] } ], "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/ScalekitEvent" }, "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", "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" } ] } }, "display_name": "Organization Created" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.updated": { "post": { "summary": "Organization Updated", "description": "Triggered when an organization is updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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", "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" } ] } }, "display_name": "Organization Updated" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.deleted": { "post": { "summary": "Organization Deleted", "description": "Triggered when an organization is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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" } ] } }, "display_name": "Organization Deleted" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.signup": { "post": { "summary": "User Signup", "description": "Triggered when a user signs up to create a new organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_1234567890", "type": "user.signup", "object": "OrgMembership", "occurred_at": "2024-01-15T10:30:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_102690563312124938", "data": { "organization": { "id": "org_102690563312124938", "create_time": "2025-12-09T10:19:05.48Z", "display_name": "", "external_id": null, "metadata": null, "region_code": "US", "update_time": "2025-12-09T12:04:41.386974738Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": true, "name": "dir_sync" } ] } }, "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "amit.ash1996@gmail.com", "external_id": "", "id": "usr_102701193205121289", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988278Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": null, "family_name": "doe", "gender": "", "given_name": "John", "groups": null, "id": "usp_102701193205186825", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } } }, "display_name": "User Signup" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.login": { "post": { "summary": "User Login", "description": "Triggered when a user logs in and a session is created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_102701193859432713", "type": "user.login", "object": "User", "occurred_at": "2025-12-09T12:04:41.781873312Z", "environment_id": "env_96736846679245078", "organization_id": "org_102701193188409609", "data": { "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "john.doe@acmecorp.com", "external_id": "ext_123456789", "id": "usr_123456789", "last_login_time": "2025-12-09T12:04:41.48Z", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_provider": "GOOGLE", "connection_type": "OAUTH", "connection_user_id": "105055379523565727691", "created_time": "2025-12-09T12:04:41.47Z", "is_social": true, "last_login_time": "2025-12-09T12:04:41.469311Z", "last_synced_time": "2025-12-09T12:04:41.469311Z" } ], "family_name": "Doe", "gender": "", "given_name": "John", "groups": null, "id": "usp_102701193205186825", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } }, "user_session": { "absolute_expires_at": "2026-01-08T12:04:41.737394Z", "authenticated_organizations": ["org_102701193188409609"], "created_at": "2025-12-09T12:04:41.48Z", "expired_at": null, "idle_expires_at": "2025-12-16T12:04:41.737395Z", "last_active_at": "2025-12-09T12:04:41.747206Z", "logout_at": null, "organization_id": "org_102701193188409609", "session_id": "ses_102701193356116233", "status": "ACTIVE", "updated_at": "2025-12-09T12:04:41.748512Z", "user_id": "usr_102701193205121289", "device": { "browser": "Chrome", "browser_version": "142.0.0.0", "device_type": "Desktop", "ip": "152.59.144.211", "location": { "city": "Patna", "latitude": "25.594095", "longitude": "85.137564", "region": "IN", "region_subdivision": "INBR" }, "os": "macOS", "os_version": "10.15.7", "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" } } }, "display_name": "User Login" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.logout": { "post": { "summary": "User Logout", "description": "Triggered when a user's session is terminated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_102708230123160586", "type": "user.logout", "object": "User", "occurred_at": "2025-12-09T13:14:35.722070822Z", "environment_id": "env_96736846679245078", "organization_id": "org_102701193188409609", "data": { "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "john.doe@acmecorp.com", "external_id": "ext_123456789", "id": "usr_123456789", "last_login_time": "2025-12-09T12:04:41.48Z", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_provider": "GOOGLE", "connection_type": "OAUTH", "connection_user_id": "105055379523565727691", "created_time": "2025-12-09T12:04:41.47Z", "is_social": true, "last_login_time": "2025-12-09T12:04:41.469311Z", "last_synced_time": "2025-12-09T12:04:41.469311Z" } ], "family_name": "Doe", "gender": "", "given_name": "John", "groups": null, "id": "usp_102701193205186825", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } }, "user_session": { "absolute_expires_at": "2026-01-08T12:04:41.737394Z", "authenticated_organizations": ["org_102701193188409609"], "created_at": "2025-12-09T12:04:41.48Z", "expired_at": null, "idle_expires_at": "2025-12-16T12:04:41.737395Z", "last_active_at": "2025-12-09T12:04:41.747206Z", "logout_at": null, "organization_id": "org_102701193188409609", "session_id": "ses_102701193356116233", "status": "ACTIVE", "updated_at": "2025-12-09T12:04:41.748512Z", "user_id": "usr_102701193205121289", "device": { "browser": "Chrome", "browser_version": "142.0.0.0", "device_type": "Desktop", "ip": "152.59.144.211", "location": { "city": "Patna", "latitude": "25.594095", "longitude": "85.137564", "region": "IN", "region_subdivision": "INBR" }, "os": "macOS", "os_version": "10.15.7", "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" } } }, "display_name": "User Logout" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_invitation": { "post": { "summary": "User Organization Invitation", "description": "Triggered when a user is invited to join an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_4567890123", "type": "user.organization_invitation", "object": "OrgMembership", "occurred_at": "2024-01-15T11:00:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_102690563312124938", "data": { "organization": { "id": "org_102690563312124938", "create_time": "2025-12-09T10:19:05.48Z", "display_name": "Acme Corp", "external_id": "org_external_123", "metadata": null, "region_code": "US", "update_time": "2025-12-09T12:04:41.386974738Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": true, "name": "dir_sync" } ] } }, "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "john.doe@acmecorp.com", "external_id": "ext_123456789", "id": "usr_123456789", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_provider": "GOOGLE", "connection_type": "OAUTH", "connection_user_id": "105055379523565727691", "created_time": "2025-12-09T12:04:41.47Z", "is_social": true, "last_login_time": "2025-12-09T12:04:41.469311Z", "last_synced_time": "2025-12-09T12:04:41.469311Z" } ], "family_name": "Doe", "gender": "", "given_name": "John", "groups": null, "id": "usp_102701193205186825", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } } }, "display_name": "User Organization Invitation" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_membership_created": { "post": { "summary": "User Organization Membership Created", "description": "Triggered when a user joins an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_5678901234", "type": "user.organization_membership_created", "object": "OrgMembership", "occurred_at": "2024-01-15T11:05:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_102690563312124938", "data": { "organization": { "id": "org_102690563312124938", "create_time": "2025-12-09T10:19:05.48Z", "display_name": "Acme Corp", "external_id": "org_external_123", "metadata": null, "region_code": "US", "update_time": "2025-12-09T12:04:41.386974738Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": true, "name": "dir_sync" } ] } }, "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "john.doe@acmecorp.com", "external_id": "ext_123456789", "id": "usr_123456789", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_provider": "GOOGLE", "connection_type": "OAUTH", "connection_user_id": "105055379523565727691", "created_time": "2025-12-09T12:04:41.47Z", "is_social": true, "last_login_time": "2025-12-09T12:04:41.469311Z", "last_synced_time": "2025-12-09T12:04:41.469311Z" } ], "family_name": "Doe", "gender": "", "given_name": "John", "groups": null, "id": "usp_102701193205186825", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } } }, "display_name": "User Organization Membership Created" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_membership_deleted": { "post": { "summary": "User Organization Membership Deleted", "description": "Triggered when a user's membership in an organization is removed or deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_9012345678", "type": "user.organization_membership_deleted", "object": "OrgMembership", "occurred_at": "2024-01-15T11:10:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_102690563312124938", "data": { "organization": { "id": "org_102690563312124938", "create_time": "2025-12-09T10:19:05.48Z", "display_name": "Acme Corp", "external_id": "org_external_123", "metadata": null, "region_code": "US", "update_time": "2025-12-09T12:04:41.386974738Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": true, "name": "dir_sync" } ] } }, "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "john.doe@acmecorp.com", "external_id": "ext_123456789", "id": "usr_123456789", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_provider": "GOOGLE", "connection_type": "OAUTH", "connection_user_id": "105055379523565727691", "created_time": "2025-12-09T12:04:41.47Z", "is_social": true, "last_login_time": "2025-12-09T12:04:41.469311Z", "last_synced_time": "2025-12-09T12:04:41.469311Z", "raw_attributes": "{}", "updated_time": "2025-12-09T12:04:41.473087Z" } ], "family_name": "Doe", "gender": "", "given_name": "John", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } } }, "display_name": "User Organization Membership Deleted" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "user.organization_membership_updated": { "post": { "summary": "User Organization Membership Updated", "description": "Triggered when a user's organization membership is updated, e.g., change of user's role in an organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_6789012345", "type": "user.organization_membership_updated", "object": "OrgMembership", "occurred_at": "2024-01-15T11:10:00.123456789Z", "environment_id": "env_1234567890", "organization_id": "org_102690563312124938", "data": { "organization": { "id": "org_102690563312124938", "create_time": "2025-12-09T10:19:05.48Z", "display_name": "Acme Corp", "external_id": "org_external_123", "metadata": null, "region_code": "US", "update_time": "2025-12-09T12:04:41.386974738Z", "settings": { "features": [ { "enabled": true, "name": "sso" }, { "enabled": true, "name": "dir_sync" } ] } }, "user": { "create_time": "2025-12-09T12:04:41.39Z", "email": "john.doe@acmecorp.com", "external_id": "ext_123456789", "id": "usr_123456789", "metadata": {}, "update_time": "2025-12-09T12:04:41.391988Z", "user_profile": { "custom_attributes": null, "email_verified": true, "external_identities": [ { "connection_id": "conn_97896332307464201", "connection_provider": "GOOGLE", "connection_type": "OAUTH", "connection_user_id": "105055379523565727691", "created_time": "2025-12-09T12:04:41.47Z", "is_social": true, "last_login_time": "2025-12-09T12:04:41.469311Z", "last_synced_time": "2025-12-09T12:04:41.469311Z", "raw_attributes": "{}", "updated_time": "2025-12-09T12:04:41.473087Z" } ], "family_name": "Doe", "gender": "", "given_name": "John", "locale": "", "metadata": {}, "name": "John Doe", "phone_number": "", "phone_number_verified": false, "picture": "https://lh3.googleusercontent.com/a/abcdef", "preferred_username": "" } } }, "display_name": "User Organization Membership Updated" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Directory Enabled" } } } }, "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/ScalekitEvent" }, "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", "enabled": false, "id": "dir_53879621145330183", "organization_id": "org_53879494091473415", "provider": "OKTA", "updated_at": "2025-01-06T18:45:21.04978184Z" }, "display_name": "Directory Disabled" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.user_created": { "post": { "summary": "Directory User Created", "description": "Triggered when a new directory user is created", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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, "cost_center": "QAUZJUHSTYCN", "custom_attributes": { "mobile_phone_number": "1-579-4072" }, "department": "HNXJPGISMIFN", "division": "MJFUEYJOKICN", "dp_id": "", "email": "flavio@runolfsdottir.co.duk", "employee_id": "AWNEDTILGaIZN", "family_name": "Jaquelin", "given_name": "Dayton", "groups": [ { "id": "dirgroup_12312312312312", "name": "Group Name" } ], "id": "diruser_53891546960887884", "language": "se", "locale": "LLWLEWESPLDC", "name": "QDRGUZZDYMFU", "nickname": "DTUODYKGFPPC", "organization": "AUIITQVUQGVH", "organization_id": "org_53879494091473415", "phone_number": "1-579-4072", "preferred_username": "kuntala1233a", "profile": "YMIUQUHKGVAX", "raw_attributes": {}, "title": "FKQBHCWJXZSC", "user_type": "RBQFJSQEFAEH", "zoneinfo": "America/Araguaina", "roles": [ { "role_name": "billing_admin" } ] }, "display_name": "Directory User Created" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.user_updated": { "post": { "summary": "Directory User Updated", "description": "Triggered when a directory user is updated", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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": { "id": "diruser_12312312312312", "organization_id": "org_53879494091473415", "dp_id": "", "preferred_username": "", "email": "john.doe@example.com", "active": true, "name": "John Doe", "roles": [ { "role_name": "billing_admin" } ], "groups": [ { "id": "dirgroup_12312312312312", "name": "Group Name" } ], "given_name": "John", "family_name": "Doe", "nickname": "Jhonny boy", "picture": "https://image.com/profile.jpg", "phone_number": "1234567892", "address": { "postal_code": "64112", "state": "Missouri", "formatted": "123, Oxford Lane, Kansas City, Missouri, 64112" }, "custom_attributes": { "attribute1": "value1", "attribute2": "value2" }, "raw_attributes": {} }, "display_name": "Directory User Updated" } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "organization.directory.user_deleted": { "post": { "summary": "Directory User Deleted", "description": "Triggered when a directory user is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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": { "id": "diruser_12312312312312", "organization_id": "org_12312312312312", "dp_id": "", "email": "john.doe@example.com" }, "display_name": "Directory User Deleted" } } } }, "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/ScalekitEvent" }, "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": "Avengers", "external_id": null, "id": "dirgroup_38862741498233423", "organization_id": "org_38609339635728478", "raw_attributes": {} }, "display_name": "Directory Group Created" } } } }, "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/ScalekitEvent" }, "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": "Avengers", "external_id": "", "id": "dirgroup_38862741498233423", "organization_id": "org_38609339635728478", "raw_attributes": {} }, "display_name": "Directory Group Updated" } } } }, "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/ScalekitEvent" }, "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": {} }, "display_name": "Directory Group Deleted" } } } }, "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/ScalekitEvent" }, "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": { "id": "conn_94567862424830277", "organization_id": "org_83544995172188677", "connection_type": "OIDC", "provider": "OKTA" }, "display_name": "SSO Connection Created" } } } }, "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/ScalekitEvent" }, "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": { "id": "conn_94567862424830277", "organization_id": "org_83544995172188677", "connection_type": "OIDC", "provider": "OKTA", "enabled": true, "status": "COMPLETED" }, "display_name": "SSO Connection Enabled" } } } }, "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/ScalekitEvent" }, "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": { "id": "conn_83545002856153607", "organization_id": "org_83544995172188677", "connection_type": "OIDC", "provider": "OKTA", "enabled": false, "status": "COMPLETED" }, "display_name": "SSO Connection Disabled" } } } }, "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/ScalekitEvent" }, "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": { "id": "conn_83545002856153607", "organization_id": "org_83544995172188677", "connection_type": "OIDC", "provider": "OKTA" }, "display_name": "SSO Connection Deleted" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Role Created" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Role Updated" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Role Deleted" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Permission Created" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Permission Updated" } } } }, "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/ScalekitEvent" }, "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" }, "display_name": "Permission Deleted" } } } }, "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/ScalekitEvent" }, "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/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_101652975398683158", "type": "connected_account.updated", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:31:34.895815554Z", "environment_id": "env_88640229614813449", "display_name": "Connected account updated", "data": { "authorization_type": "OAUTH", "connection_id": "conn_100510054016352776", "id": "ca_100510623602835982", "identifier": "Pranesh", "provider": "SUPABASE", "status": "PENDING_AUTH" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.deleted": { "post": { "summary": "Connected Account Deleted", "description": "Triggered when a connected account is deleted", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_101653010731500290", "type": "connected_account.deleted", "object": "ConnectedAccount", "occurred_at": "2025-12-02T06:31:55.954027187Z", "environment_id": "env_88640229614813449", "display_name": "connected account deleted", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649788113519113", "identifier": "Clark", "last_used_at": "2025-12-02T06:00:01.374253Z", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:59:57.237447Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.magic_link_generated": { "post": { "summary": "Connected Account Magic Link Generated", "description": "Triggered when a magic link is generated for OAuth flow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_101649795042509316", "type": "connected_account.oauth_tokens_fetched", "object": "ConnectedAccount", "occurred_at": "2025-12-02T05:59:59.250126407Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649788113519113", "identifier": "Clark", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:59:57.237447778Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } }, "connected_account.token_refresh_succeeded": { "post": { "summary": "Connected Account Token Refresh Succeeded", "description": "Triggered when token refresh succeeds", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScalekitEvent" }, "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/ScalekitEvent" }, "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/ScalekitEvent" }, "example": { "spec_version": "1", "id": "evt_101649484227871236", "type": "connected_account.oauth_succeeded", "object": "ConnectedAccount", "occurred_at": "2025-12-02T05:56:53.994604757Z", "environment_id": "env_88640229614813449", "data": { "authorization_type": "OAUTH", "connection_id": "conn_101644109747323155", "id": "ca_101649474950005257", "identifier": "Bruce", "provider": "GOOGLE_ADS", "status": "ACTIVE", "token_expires_at": "2025-12-02T06:56:52.976081699Z" } } } } }, "responses": { "200": { "description": "Webhook received successfully" } } } } } }