info:
  description: |
    # Overview

    The Scalekit API is a RESTful API that enables you to manage organizations, users, and authentication settings. All requests must use HTTPS.
    All API requests use the following base URLs:

    ```
    https://{your-subdomain}.scalekit.dev (Development)
    https://{your-subdomain}.scalekit.com (Production)
    https://auth.yourapp.com (Custom domain)
    ```

    Scalekit operates two separate environments: Development and Production. Resources cannot be moved between environments.

    ## Quickstart

    The Scalekit API uses OAuth 2.0 Client Credentials for authentication.

    Copy your API credentials from the Scalekit dashboard's API Config section and set them as environment variables.

    ```sh
    SCALEKIT_ENVIRONMENT_URL='<YOUR_ENVIRONMENT_URL>'
    SCALEKIT_CLIENT_ID='<ENVIRONMENT_CLIENT_ID>'
    SCALEKIT_CLIENT_SECRET='<ENVIRONMENT_CLIENT_SECRET>'
    ```

    Getting an access token

    1. Get your credentials from the [Scalekit Dashboard](https://app.scalekit.com)
    2. Request an access token:

    ```sh
    curl https://<SCALEKIT_ENVIRONMENT_URL>/oauth/token \
      -X POST \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'client_id={client_id}' \
      -d 'client_secret={client_secret}' \
      -d 'grant_type=client_credentials'
    ```

    3. Use the access token in API requests:

    ```sh
    curl https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer {access_token}'
    ```

    The response includes an access token:

    ```json
    {
    	"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNua181Ok4OTEyMjU2NiIsInR5cCI6IkpXVCJ9...",
    	"token_type": "Bearer",
    	"expires_in": 86399,
    	"scope": "openid"
    }
    ```

    ## SDKs

    Scalekit provides official SDKs for multiple programming languages. Check the changelog at GitHub repositories for the latest updates.

    ### Node.js

    ```sh
    npm install @scalekit-sdk/node
    ```

    Create a new Scalekit client instance after initializing the environment variables

    ```js
    import { Scalekit } from "@scalekit-sdk/node";

    export let scalekit = new Scalekit(
    	process.env.SCALEKIT_ENVIRONMENT_URL,
    	process.env.SCALEKIT_CLIENT_ID,
    	process.env.SCALEKIT_CLIENT_SECRET
    );
    ```

    [See the Node SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-node/releases)

    ### Python

    ```sh
    pip install scalekit-sdk-python
    ```

    Create a new Scalekit client instance after initializing the environment variables.

    ```py
    from scalekit import ScalekitClient
    import os

    scalekit_client = ScalekitClient(
        os.environ.get('SCALEKIT_ENVIRONMENT_URL'),
        os.environ.get('SCALEKIT_CLIENT_ID'),
        os.environ.get('SCALEKIT_CLIENT_SECRET')
    )
    ```

    [See the Python SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-python/releases)

    ### Go

    ```sh
    go get -u github.com/scalekit-inc/scalekit-sdk-go
    ```

    Create a new Scalekit client instance after initializing the environment variables.

    ```go
    package main

    import (
        "os"
        "github.com/scalekit-inc/scalekit-sdk-go"
    )

    scalekitClient := scalekit.NewScalekitClient(
        os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
        os.Getenv("SCALEKIT_CLIENT_ID"),
        os.Getenv("SCALEKIT_CLIENT_SECRET"),
    )
    ```

    [See the Go SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-go/releases)

    ### Java

    ```gradle
    /* Gradle users - add the following to your dependencies in build file */
    implementation "com.scalekit:scalekit-sdk-java:2.0.11"
    ```

    ```xml
    <!-- Maven users - add the following to your `pom.xml` -->
    <dependency>
        <groupId>com.scalekit</groupId>
        <artifactId>scalekit-sdk-java</artifactId>
        <version>2.0.11</version>
    </dependency>
    ```

    [See the Java SDK changelog](https://github.com/scalekit-inc/scalekit-sdk-java/releases)

    ### Error handling

    The API uses standard HTTP status codes:

    | Code        | Description          |
    | ----------- | -------------------- |
    | 200/201     | Success              |
    | 400         | Invalid request      |
    | 401         | Authentication error |
    | 404         | Resource not found   |
    | 429         | Rate limit exceeded  |
    | 500/501/504 | Server error         |

    Error responses include detailed information:

    ```json
    {
    	"code": 16,
    	"message": "Token empty",
    	"details": [
    		{
    			"@type": "type.googleapis.com/scalekit.v1.errdetails.ErrorInfo",
    			"error_code": "UNAUTHENTICATED"
    		}
    	]
    }
    ```
  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: |2

        # 1. Obtain API Credentials
        # Get your credentials from the Scalekit dashboard
        export SCALEKIT_ENVIRONMENT_URL="https://your-org.scalekit.dev" # Your Scalekit environment URL
        export SCALEKIT_CLIENT_ID="your_client_id"                      # Your client ID
        export SCALEKIT_CLIENT_SECRET="your_client_secret"              # Your client secret

        # 2. Exchange client credentials an OAuth 2.0 access token
        TOKEN_RESPONSE=$(curl -s -X POST "${SCALEKIT_ENVIRONMENT_URL}/oauth/token" \
          -H "Content-Type: application/x-www-form-urlencoded" \
          -d "client_id=${SCALEKIT_CLIENT_ID}" \
          -d "client_secret=${SCALEKIT_CLIENT_SECRET}" \
          -d "grant_type=client_credentials")

        # 3. Make Authenticated API Requests
        curl -X GET "${SCALEKIT_ENVIRONMENT_URL}/api/v1/organizations" \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer ${ACCESS_TOKEN}" \
          -H "Accept: application/json"

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

            const connections = await
            scalekit.connection.listConnections(organizationId);


            // List connections by domain

            const connections = await
            scalekit.connection.listConnectionsByDomain(domain);
        - label: Python SDK
          lang: python
          source: |-
            # List connections by organization id
            connections = scalekit_client.connection.list_connections(
              organization_id
            )

            # List connections by domain
            response = scalekit_client.connection.list_connections_by_domain(domain="example.com")
        - label: Go SDK
          lang: go
          source: >-
            // List connections by organization id

            connections, err := scalekitClient.Connection().ListConnections(
              ctx,
              organizationId
            )


            // List connections by domain

            connections, err :=
            scalekitClient.Connection().ListConnectionsByDomain(ctx, 
              domain)
        - label: Java SDK
          lang: java
          source: |-
            // List connections by organization id
            ListConnectionsResponse response = scalekitClient.connections(
              ).listConnections(organizationId);

            // List connections by domain
            ListConnectionsResponse response = scalekitClient.connections(
              ).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";
            const scalekit = new ScalekitClient(
            	process.env.SCALEKIT_ENV_URL,
            	process.env.SCALEKIT_CLIENT_ID,
            	process.env.SCALEKIT_CLIENT_SECRET
            );
            await scalekit.user.createMembership("org_123", "usr_123", {
            	roles: ["admin"],
            	metadata: {
            		department: "engineering",
            		location: "nyc-office",
            	},
            });
        - label: Python SDK
          lang: python
          source: >-
            from scalekit.v1.users.users_pb2 import CreateMembership

            from scalekit.v1.commons.commons_pb2 import Role


            membership = CreateMembership(
                roles=[Role(name="admin")],
                metadata={"department": "engineering", "location": "nyc-office"},
            )

            resp = scalekit_client.users.create_membership(
                organization_id="org_123",
                user_id="usr_123",
                membership=membership,
            )
        - label: Go SDK
          lang: go
          source: |-
            func main() {
                scalekitClient := scalekit.NewScalekitClient(
                    os.Getenv("SCALEKIT_ENV_URL"),
                    os.Getenv("SCALEKIT_CLIENT_ID"),
                    os.Getenv("SCALEKIT_CLIENT_SECRET"),
                )
                membership := &usersv1.CreateMembership{
                    Roles: []*usersv1.Role{{Name: "admin"}},
                    Metadata: map[string]string{
                        "department": "engineering",
                        "location":   "nyc-office",
                    },
                }
                resp, 
                  err := scalekitClient.User().CreateMembership(
                    context.Background(), "org_123", 
                      "usr_123", membership, false)
                if err != nil {
                    panic(err)
                }
            }
        - label: Java SDK
          lang: java
          source: |-
            import com.scalekit.ScalekitClient;
            import com.scalekit.api.UserClient;
            import com.scalekit.grpc.scalekit.v1.users.*;
            ScalekitClient scalekitClient = new ScalekitClient(
                System.getenv("SCALEKIT_ENV_URL"),
                System.getenv("SCALEKIT_CLIENT_ID"),
                System.getenv("SCALEKIT_CLIENT_SECRET")
            );
            UserClient users = scalekitClient.users();
            CreateMembershipRequest membershipReq = CreateMemb
              ershipRequest.newBuilder()
                    .setMembership(
                      CreateMembership.newBuilder()
                            .addRoles(Role.newBuilder(
                              ).setName("admin").build())
                            .putMetadata("department", "engineering")
                            .putMetadata("location", "nyc-office")
                            .build())
                    .build();
            CreateMembershipResponse res = users.
              createMembership("org_123", "usr_123", 
                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(
              organization_id=org_id,user_id=user_id
            )
    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({
            	pageSize: 10,
            });
        - label: Python SDK
          lang: python
          source: |-
            options = ListOrganizationOptions()
            options.page_size = 10

            organizations = scalekit_client.organization.list_organizations(
              options=options
            )
        - label: Go SDK
          lang: go
          source: |-
            organizations, err := scalekitClient.Organization.ListOrganizations(
              ctx,
              &scalekit.ListOrganizationOptions{
                PageSize: 10,
              }
            )
        - 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, {

            	externalId: "externalId",

            });
        - label: Python SDK
          lang: python
          source: |-
            options = CreateOrganizationOptions()
            options.external_id = "externalId"
            organization = scalekit_client.organization.create_organization(
              name,
              options=options
            )
        - label: Go SDK
          lang: go
          source: |-
            organization, err := ScalekitClient.Organization.CreateOrganization(
              ctx,
              name,
              scalekit.CreateOrganizationOptions{
                ExternalID: "externalId",
              },
            )
        - label: Java SDK
          lang: java
          source: >-
            CreateOrganization createOrganization =
            CreateOrganization.newBuilder()
              .setDisplayName("Test Org")
              .build();

            Organization 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(
              <SCALEKIT_ENVIRONMENT_URL>,
              <SCALEKIT_CLIENT_ID>,
              <SCALEKIT_CLIENT_SECRET>
            );


            const organization = await
            scalekit.organization.getOrganization(organization_id);
        - label: Python SDK
          lang: python
          source: |-
            scalekit_client = ScalekitClient(
              <SCALEKIT_ENVIRONMENT_URL>,
              <SCALEKIT_CLIENT_ID>,
              <SCALEKIT_CLIENT_SECRET>
            )

            organization = scalekit_client.organization.get_organization(
              organization_id
            )
        - label: Go SDK
          lang: go
          source: |-
            scalekitClient := scalekit.NewScalekitClient(
              <SCALEKIT_ENVIRONMENT_URL>,
              <SCALEKIT_CLIENT_ID>,
              <SCALEKIT_CLIENT_SECRET>
            )

            organization, err := scalekitClient.Organization.GetOrganization(
              ctx,
              organizationId
            )
        - label: Java SDK
          lang: java
          source: >-
            ScalekitClient scalekitClient = new ScalekitClient(
              "<SCALEKIT_ENVIRONMENT_URL>",
              "<SCALEKIT_CLIENT_ID>",
              "<SCALEKIT_CLIENT_SECRET>"
            );


            Organization 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(
              ctx,
              organizationId
            )
        - label: Java SDK
          lang: java
          source: |-
            ScalekitClient scalekitClient = new ScalekitClient(
              "<SCALEKIT_ENVIRONMENT_URL>",
              "<SCALEKIT_CLIENT_ID>",
              "<SCALEKIT_CLIENT_SECRET>"
            );

            scalekitClient.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, {
              displayName: 'displayName',
              externalId: 'externalId',
            });
        - label: Python SDK
          lang: python
          source: >-
            organization =
            scalekit_client.organization.update_organization(organization_id, {
              display_name: "display_name",
              external_id: "external_id"
            })
        - label: Go SDK
          lang: go
          source: |-
            organization, err := scalekitClient.Organization.UpdateOrganization(
              ctx,
              organizationId,
              &scalekit.UpdateOrganization{
                DisplayName: "displayName",
                ExternalId: "externalId",
              },
            )
        - label: Java SDK
          lang: java
          source: >-
            UpdateOrganization updateOrganization =
            UpdateOrganization.newBuilder()
              .setDisplayName("Updated Organization Name")
              .build();

            Organization 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:


            - Single Sign-On: ?features=sso

            - Directory Sync: ?features=dir_sync

            - Both features: ?features=sso&features=dir_sync


            Example URL: https://scalekit.com/portal/lnk_123?features=sso

             - dir_sync: Enables directory synchronization configuration in the portal
             - 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(
              organization_id
            )
        - label: Go SDK
          lang: go
          source: |-
            link, err := scalekitClient.Organization.GeneratePortalLink(
              ctx,
              organizationId
            )
        - label: Java SDK
          lang: java
          source: >-
            Link portalLink = client
              .organizations()
              .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 = {
              features: [
                {
                  name: 'sso',
                  enabled: true,
                },
                {
                  name: 'dir_sync',
                  enabled: true,
                },
              ],
            };

            await scalekit.organization.updateOrganizationSettings('<organization_id>', settings);
        - label: Python SDK
          lang: python
          source: |-
            settings = [
                    {
                        "name": "sso",
                        "enabled": True
                    },
                    {
                        "name": "dir_sync",
                        "enabled": True
                    }
                ]

            scalekit_client.organization.update_organization_settings(
              organization_id='<organization_id>', settings=settings
            )
        - label: Go SDK
          lang: go
          source: >-
            settings := OrganizationSettings{

            		Features: []Feature{

            			{

            				Name:    "sso",

            				Enabled: true,

            			},

            			{

            				Name:    "dir_sync",

            				Enabled: true,

            			},

            		},

            	}


            organization,err :=
            scalekitClient.Organization().UpdateOrganizationSettings(ctx,
            organizationId, settings)
        - label: Java SDK
          lang: java
          source: >-
            OrganizationSettingsFeature featureSSO =
            OrganizationSettingsFeature.newBuilder()
                            .setName("sso")
                            .setEnabled(true)
                            .build();

            OrganizationSettingsFeature featureDirectorySync =
            OrganizationSettingsFeature.newBuilder()
                            .setName("dir_sync")
                            .setEnabled(true)
                            .build();

            updatedOrganization = scalekitClient.organizations()
                            .updateOrganizationSettings(organization.getId(), List.of(featureSSO,
            featureDirectorySync));
      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")

            if err != nil { /* handle err */ }

            _ = 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", {
              name: "org_admin",
              displayName: "Org Admin",
              description: "Organization-scoped role",
               extends: "base_role_name", // optional
               permissions: ["perm.read", "perm.write"] // optional
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import CreateOrganizationRole

            role = CreateOrganizationRole(
                name="org_admin",
                display_name="Org Admin",
                description="Organization-scoped role",
                extends="base_role_name",              # optional
                permissions=["perm.read", "perm.write"]  # optional
            )

            scalekit_client.roles.create_organization_role(
                org_id="org_123",
                role=role
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Role().CreateOrganizationRole(ctx,
            "org_123", &rolesv1.CreateOrganizationRole{

            	Name:        "org_admin",

            	DisplayName: "Org Admin",

            	Description: proto.String("Organization-scoped role"), // optional

            	Extends:     proto.String("base_role_name"),        // optional

            	Permissions: []string{"perm.read", "perm.write"},   // optional

            })
        - label: Java SDK
          lang: java
          source: >-
            CreateOrganizationRoleResponse res =
            scalekitClient.roles().createOrganizationRole(
                "org_123",
                CreateOrganizationRoleRequest.newBuilder()
                    .setOrgId("org_123")
                    .setRole(
                        CreateOrganizationRole.newBuilder()
                            .setName("org_admin")
                            .setDisplayName("Org Admin")
                            .setDescription("Organization-scoped role")
                            .setExtends("base_role_name")          // optional
                            .addPermissions("perm.read")           // optional
                            .addPermissions("perm.write")          // optional
                            .build()
                    )
                    .build()
            );
      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(
                org_id="org_123",
                role_name="org_admin"
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Role().GetOrganizationRole(ctx,
            "org_123", "org_admin")

            if err != nil { /* handle err */ }

            _ = 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", {
              displayName: "Org Admin (Updated)",
              description: "Updated org role description"
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import UpdateRole

            scalekit_client.roles.update_organization_role(
                org_id="org_123",
                role_name="org_admin",
                role=UpdateRole(
                    display_name="Org Admin (Updated)",
                    description="Updated org role description"
                )
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Role().UpdateOrganizationRole(ctx,
            "org_123", "org_admin", &rolesv1.UpdateRole{
                DisplayName: "Org Admin (Updated)",
                Description: "Updated org role description",
            })

            if err != nil { /* handle err */ }

            _ = resp
        - label: Java SDK
          lang: java
          source: >-
            UpdateOrganizationRoleResponse res =
            scalekitClient.roles().updateOrganizationRole(
                "org_123",
                "org_admin",
                UpdateOrganizationRoleRequest.newBuilder()
                    .setRole(
                        UpdateRole.newBuilder()
                            .setDisplayName("Org Admin (Updated)")
                            .setDescription("Updated org role description")
                            .build()
                    )
                    .build()
            );
      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

            await scalekit.role.deleteOrganizationRole("org_123",
            "org_role_admin");


            // With reassignment

            await scalekit.role.deleteOrganizationRole("org_123",
            "org_role_admin", "org_role_member");
        - label: Python SDK
          lang: python
          source: |-
            # Basic delete
            scalekit_client.roles.delete_organization_role(
                org_id="org_123",
                role_name="org_role_admin"
            )

            # With reassignment
            scalekit_client.roles.delete_organization_role(
                org_id="org_123",
                role_name="org_role_admin",
                reassign_role_name="org_role_member"
            )
        - label: Go SDK
          lang: go
          source: >-
            // Basic delete

            err := scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123",
            "org_role_admin")

            if err != nil { /* handle err */ }


            // With reassignment

            err = scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123",
            "org_role_admin", "org_role_member")
        - label: Java SDK
          lang: java
          source: >-
            // Basic delete

            scalekitClient.roles().deleteOrganizationRole("org_123",
            "org_role_admin");


            // With reassignment

            scalekitClient.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", {
              defaultMemberRole: "org_member"
            });
        - label: Python SDK
          lang: python
          source: >-
            from scalekit.v1.roles.roles_pb2 import
            UpdateDefaultOrganizationRolesRequest


            res = scalekit_client.roles.update_default_organization_roles(
                org_id="org_123",
                default_roles=UpdateDefaultOrganizationRolesRequest(
                    default_member_role="org_member"
                )
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err :=
            scalekitClient.Role().UpdateDefaultOrganizationRoles(ctx, "org_123",
            "org_member")

            if err != nil { /* handle err */ }

            _ = resp
        - label: Java SDK
          lang: java
          source: >-
            UpdateDefaultOrganizationRolesResponse res =
            scalekitClient.roles().updateDefaultOrganizationRoles(
                "org_123",
                UpdateDefaultOrganizationRolesRequest.newBuilder()
                    .setDefaultMemberRole("org_member")
                    .build()
            );
      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


            Maximum 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


            Pagination 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

            org_id = 'SCALEKIT_ORGANIZATION_ID'


            # Retrieve all clients with default pagination

            response = scalekit_client.m2m_client.list_organization_clients(
                organization_id=org_id,
                page_size=30
            )


            # Access the clients list

            clients = response.clients

            for client in clients:
                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


            m2m_client = OrganizationClient(
                name="GitHub Actions Deployment Service",
                description="Service account for GitHub Actions to deploy applications
            to production",
                custom_claims=[
                    {"key": "github_repository", "value": "acmecorp/inventory-service"},
                    {"key": "environment", "value": "production_us"}
                ],
                scopes=["deploy:applications", "read:deployments"],
                audience=["deployment-api.acmecorp.com"],
                expiry=3600
            )


            response = scalekit_client.m2m_client.create_organization_client(
                organization_id="SCALEKIT_ORGANIZATION_ID",
                m2m_client=m2m_client
            )
      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
            org_id = 'SCALEKIT_ORGANIZATION_ID'
            client_id = os.environ['M2M_CLIENT_ID']

            # Fetch client details for the specified organization
            response = scalekit_client.m2m_client.get_organization_client(
                organization_id=org_id,
                client_id=client_id
            )
    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
            org_id = '<SCALEKIT_ORGANIZATION_ID>'
            client_id = os.environ['M2M_CLIENT_ID']

            # Delete the specified client from the organization
            response = scalekit_client.m2m_client.delete_organization_client(
                organization_id=org_id,
                client_id=client_id
            )
    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


            org_id = '<SCALEKIT_ORGANIZATION_ID>'

            client_id = os.environ['M2M_CLIENT_ID']


            update_m2m_client = OrganizationClient(
                description="Service account for GitHub Actions to deploy applications
            to production_eu",
                custom_claims=[
                    {"key": "github_repository", "value": "acmecorp/inventory"},
                    {"key": "environment", "value": "production_eu"}
                ]
            )


            response = scalekit_client.m2m_client.update_organization_client(
                organization_id=org_id,
                client_id=client_id,
                m2m_client=update_m2m_client
            )
      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

            org_id = 'SCALEKIT_ORGANIZATION_ID'

            client_id = os.environ['M2M_CLIENT_ID']


            # Add a new secret to the specified client

            response =
            scalekit_client.m2m_client.add_organization_client_secret(
                organization_id=org_id,
                client_id=client_id
            )


            # Extract the secret ID from the response

            secret_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

            org_id = '<SCALEKIT_ORGANIZATION_ID>'

            client_id = os.environ['M2M_CLIENT_ID']

            secret_id = os.environ['M2M_SECRET_ID']


            # Remove the specified secret from the client

            response =
            scalekit_client.m2m_client.remove_organization_client_secret(
                organization_id=org_id,
                client_id=client_id,
                secret_id=secret_id
            )
  /api/v1/organizations/{organization_id}/connections/{id}:
    get:
      description: Retrieves the complete configuration and status details for a
        specific connection by its ID within an organization. Returns all
        connection properties including provider settings, protocols, and
        current status.
      tags:
        - Connections
      summary: Get connection details
      operationId: ConnectionService_GetConnection
      parameters:
        - schema:
            type: string
          description: Organization identifier (required). Specifies which
            organization owns the connection you want to retrieve.
          name: organization_id
          in: path
          required: true
        - schema:
            type: string
          description: Connection identifier (required). Specifies which
            specific connection to retrieve from the organization.
          name: id
          in: path
          required: true
      responses:
        '200':
          description: Successfully retrieved connection details for the
            specified organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/connectionsGetConnectionResponse'
      x-codeSamples:
        - label: Node.js SDK
          lang: javascript
          source: |-
            const connection = await scalekit.connection.getConnection(
              organizationId,
              connectionId
            );
        - label: Python SDK
          lang: python
          source: |-
            connection = scalekit_client.connection.get_connection(
              organization_id,
              connection_id,
            )
        - label: Go SDK
          lang: go
          source: |-
            connection, err := scalekitClient.Connection.GetConnection(
              ctx,
              organizationId,
              connectionId,
            )
        - 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(
              organization_id,
              connection_id
            )
        - label: Go SDK
          lang: go
          source: |-
            err := scalekitClient.Connection.DeleteConnection(
              ctx,
              organizationId,
              connectionId,
            )
        - 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(
              organization_id,
              connection_id
            )
        - label: Go SDK
          lang: go
          source: |-
            err := scalekitClient.Connection.DisableConnection(
              ctx,
              organizationId,
              connectionId,
            )
        - 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(
              organization_id,
              connection_id,
            )
        - label: Go SDK
          lang: go
          source: |-
            err := scalekitClient.Connection.EnableConnection(
              ctx,
              organizationId,
              connectionId,
            )
        - 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('<organization_id>');
        - label: Python SDK
          lang: python
          source: |-
            directories_list = scalekit_client.directory.list_directories(
            	organization_id='<organization_id>'
            )
        - 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(
              '<organization_id>',
              '<directory_id>'
            );
        - label: Python SDK
          lang: python
          source: |-
            directory_groups = scalekit_client.directory.list_directory_groups(
              directory_id='<directory_id>', organization_id='<organization_id>'
            )
        - label: Go SDK
          lang: go
          source: >-
            options := &ListDirectoryGroupsOptions{

            		PageSize: 10,

            		PageToken:"",

            	}


            directoryGroups, err :=
            scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId,
            directoryId, options)
        - label: Java SDK
          lang: java
          source: |-
            var options = ListDirectoryResourceOptions.builder()
              .pageSize(10)
              .pageToken("")
              .includeDetail(true)
              .build();

            ListDirectoryGroupsResponse groupsResponse = scalekitClient
              .directories()
              .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(
              '<organization_id>',
              '<directory_id>'
            );
        - label: Python SDK
          lang: python
          source: |-
            directory_users = scalekit_client.directory.list_directory_users(
              directory_id='<directory_id>', organization_id='<organization_id>'
            )
        - label: Go SDK
          lang: go
          source: >-
            options := &ListDirectoryUsersOptions{

            		PageSize: 10,

            		PageToken: "",

            	}

            directoryUsers,err :=
            scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId,
            directoryId, options)
        - label: Java SDK
          lang: java
          source: |-
            var options = ListDirectoryResourceOptions.builder()
              .pageSize(10)
              .pageToken("")
              .includeDetail(true)
              .build();

            ListDirectoryUsersResponse usersResponse = scalekitClient
              .directories()
              .listDirectoryUsers(directory.getId(), organizationId, options);
  /api/v1/organizations/{organization_id}/directories/{id}:
    get:
      description: Retrieves detailed information about a specific directory
        within an organization
      tags:
        - Directory
      summary: Get directory details
      operationId: DirectoryService_GetDirectory
      parameters:
        - schema:
            type: string
          description: Unique identifier of the organization
          name: organization_id
          in: path
          required: true
        - schema:
            type: string
          description: Unique identifier of the directory
          name: id
          in: path
          required: true
      responses:
        '200':
          description: Successfully retrieved directory details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/directoriesGetDirectoryResponse'
      x-codeSamples:
        - label: Node.js SDK
          lang: javascript
          source: |-
            const { directory } = await scalekit.directory.getDirectory(
              organizationId,
              directoryId
            );
        - label: Python SDK
          lang: python
          source: |-
            directory = scalekit_client.directory.get_directory(
              directory_id='<directory_id>', organization_id='<organization_id>'
            )
            print(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(
              '<organization_id>',
              '<directory_id>'
            );
        - label: Python SDK
          lang: python
          source: |-
            directory_response = scalekit_client.directory.disable_directory(
              directory_id='<directory_id>', organization_id='<organization_id>'
            )
        - label: Go SDK
          lang: go
          source: disable,err :=
            scalekitClient.Directory().DisableDirectory(ctx, organizationId,
            directoryId)
        - label: Java SDK
          lang: java
          source: |-
            ToggleDirectoryResponse disableResponse = scalekitClient
              .directories()
              .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('<organization_id>',
            '<directory_id>');
        - label: Python SDK
          lang: python
          source: |-
            directory_response = scalekit_client.directory.enable_directory(
              directory_id='<directory_id>', organization_id='<organization_id>'
            )
        - label: Go SDK
          lang: go
          source: enable,err := scalekitClient.Directory().EnableDirectory(ctx,
            organizationId, directoryId)
        - label: Java SDK
          lang: java
          source: |-
            ToggleDirectoryResponse enableResponse = client
              .directories()
              .enableDirectory(directoryId, organizationId);
  /api/v1/organizations/{organization_id}/domains:
    get:
      description: >+
        Retrieves a paginated list of all domains configured for the specified
        organization.


        Domain types:

        - ALLOWED_EMAIL_DOMAIN: Trusted domains used to suggest the organization
        in the organization switcher during sign-in/sign-up (auth-method
        agnostic).

        - ORGANIZATION_DOMAIN: SSO discovery domains used to route users to the
        correct SSO provider and enforce SSO.

      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.

            - ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the
            organization in the organization switcher during sign-in/sign-up.

            - ORGANIZATION_DOMAIN: SSO discovery domain used to route users to
            the correct SSO provider and enforce SSO.
          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
            const response = await scalekit.domain.listDomains(organizationId, {
            	domainType: "ORGANIZATION_DOMAIN"
            });

            // Domain object contains:
            // - id: Domain identifier
            // - domain: Domain name
            // - organizationId: Owning organization
            // - domainType: Configuration type
        - label: Python SDK
          lang: python
          source: |-
            # List all domains in an organization
            response = scalekit_client.domain.list_domains(
                        organization_id="org_123",
                        domain_type="ORGANIZATION_DOMAIN"
                    )
            # - organization_id: Owning organization
            # - domain_type: domain type
        - label: Go SDK
          lang: go
          source: >-
            domains, err := scalekitClient.Domain().ListDomains(ctx, "org_id",
            &scalekit.ListDomainOptions{

            DomainType: "ORGANIZATION_DOMAIN",

            })
        - label: Java SDK
          lang: java
          source: List<Domain> domains =
            scalekitClient.domains().listDomainsByOrganizationId("org_id",
            "ORGANIZATION_DOMAIN");
    post:
      description: >+
        Creates and associates a domain with an organization.


        Use one of the following domain types:

        - ALLOWED_EMAIL_DOMAIN: Adds a trusted email domain for organization
        suggestions in the organization switcher during sign-in/sign-up
        (auth-method agnostic).

        - 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.


        The domain must be a valid business domain that you control.
        Public/disposable domains (e.g., gmail.com) are blocked for security.

      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

            const response = await scalekit.createDomain("org-123",
            "example.com", {

            	// Domain type: controls user authentication and email validation

            	domainType: "ORGANIZATION_DOMAIN",

            });
        - label: Python SDK
          lang: python
          source: >-
            # Add a new domain to an organization

            response =
            scalekit_client.domain.create_domain(organization_id="org-123",

            			domain_name="example.com",
             			domain_type="ORGANIZATION_DOMAIN")
        - label: Go SDK
          lang: go
          source: >-
            domain, err := scalekitClient.Domain().CreateDomain(ctx, "org_id",
            "example.com", &scalekit.CreateDomainOptions{

            		DomainType: "ORGANIZATION_DOMAIN",

            	})
        - label: Java SDK
          lang: java
          source: |-
            CreateDomainRequest request = CreateDomainRequest.newBuilder()
            	.setOrganizationId(organization.getId())
            	.setDomain(CreateDomain.newBuilder()
            		.setDomain("example.com")
            		.setDomainType("ORGANIZATION_DOMAIN")
            		.build())
            	.build();
            	
            Domain 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.

      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

            const response = await scalekit.domain.getDomain(organizationId,
            domainId);


            // Domain object properties:

            // - id: Domain identifier

            // - domain: Domain name

            // - organizationId: Owning organization

            // - domainType: Domain configuration type
        - label: Python SDK
          lang: python
          source: >-
            # Fetch details of a specific domain

            response =
            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.


        - Deleting an ORGANIZATION_DOMAIN disables SSO routing/enforcement for
        that domain.

        - Deleting an ALLOWED_EMAIL_DOMAIN stops organization suggestions for
        users with that email domain.

      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

            // Caution: Deletion is permanent and may affect user access

            const response = await scalekit.domain.deleteDomain(organizationId,
            domainId);
        - label: Python SDK
          lang: python
          source: |-
            # Remove a domain from an organization
            # Caution: Deletion is permanent and may affect user access
            response = scalekit_client.domain.delete_domain(
                organization_id="org_123",
                domain_id="dom_123"
            )
        - 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.
              listOrganizationUsers("org_123", {
            	pageSize: 50,
            });
            console.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, 
              err := scalekitClient.User().ListOrganizationUsers(ctx, "org_123", &scalekit.ListUsersOptions{PageSize:
            50})
            if err != nil { /* handle error */ }

            fmt.Println(list.Users)
        - label: Java SDK
          lang: java
          source: |-
            ListOrganizationUsersRequest listReq = ListOrganiz
              ationUsersRequest.newBuilder()
                    .setPageSize(50)
                    .build();
            ListOrganizationUsersResponse list = users.
              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 {
               user } = await scalekit.user.
                createUserAndMembership("org_123", {
            	email: "user@example.com",
            	externalId: "ext_12345a67b89c",
            	metadata: { department: "engineering", 
            	  location: "nyc-office" },
            	userProfile: {
            		firstName: "John",
            		lastName: "Doe",
            	},
            });
        - label: Python SDK
          lang: python
          source: >-
            # Create user with membership 

            user = CreateUser(
                email="john.doe@example.com",
                external_id="ext_john_123",  # Optional
                user_profile={
                    "first_name": "John",
                    "last_name": "Doe",
                    "name": "John Doe",
                    "locale": "en-US",
                    "phone_number": "+14155552671"
                },
                membership={
                    "roles": [{"name": "member"}]  
                }
            )


            # Create user and membership in organization

            response = scalekit_client.users.create_user_and_membership(
                organization_id="your_org_id",
                user=user,
                send_invitation_email=True  # Set to False if you don't want to send
            email
            )

                user_id = response[0].user.id
        - label: Go SDK
          lang: go
          source: >-
            newUser := &usersv1.CreateUser{
                Email:      "user@example.com",
                ExternalId: "ext_12345a67b89c",
                Metadata: map[string]string{
                    "department": "engineering",
                    "location":   "nyc-office",
                },
                UserProfile: &usersv1.CreateUserProfile{
                    FirstName: "John",
                    LastName:  "Doe",
                },
            }

            cuResp, 
              err := scalekitClient.User().CreateUserAndMembership(ctx, "org_123",
            newUser, false)
            if err != nil { /* handle error */ }
        - label: Java SDK
          lang: java
          source: |-
            CreateUser createUser = CreateUser.newBuilder()
                    .setEmail("user@example.com")
                    .setExternalId("ext_12345a67b89c")
                    .putMetadata("department", "engineering")
                    .putMetadata("location", "nyc-office")
                    .setUserProfile(
                      CreateUserProfile.newBuilder()
                            .setFirstName("John")
                            .setLastName("Doe")
                            .build())
                    .build();
            CreateUserAndMembershipRequest cuReq = CreateUserA
              ndMembershipRequest.newBuilder()
                    .setUser(createUser)
                    .build();
            CreateUserAndMembershipResponse cuResp = users.
              createUserAndMembership("org_123", cuReq);
            System.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(
                organization_id="org_123",
                user_id="usr_123",
            )
            permissions = resp.permissions
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.User().ListUserPermissions(ctx,
            "org_123", "usr_123")

            if err != nil {
                // handle error
            }

            permissions := resp.Permissions
        - label: Java SDK
          lang: java
          source: >-
            ListUserPermissionsResponse resp =
            scalekitClient.users().listUserPermissions("org_123", "usr_123");

            List<Permission> 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(
                organization_id="org_123",
                user_id="usr_123",
            )
            roles = resp.roles
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.User().ListUserRoles(ctx, "org_123",
            "usr_123")

            if err != nil {
                // handle error
            }

            roles := resp.Roles
        - label: Java SDK
          lang: java
          source: >-
            ListUserRolesResponse resp =
            scalekitClient.users().listUserRoles("org_123", "usr_123");

            List<Role> 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;

            const resendResponse = await
            scalekit.passwordless.resendPasswordlessEmail(

            	authRequestId

            );
        - label: Python SDK
          lang: python
          source: >-
            resend_response =
            scalekit_client.passwordless.resend_passwordless_email(
                auth_request_id=auth_request_id,
            )


            # New auth request ID from resend

            new_auth_request_id = resend_response[0].auth_request_id
        - label: Go SDK
          lang: go
          source: >-
            resendResponse, err :=
            scalekitClient.Passwordless().ResendPasswordlessEmail(
                ctx,
                authRequestId,
            )


            if err != nil {
                // Handle error
                return
            }
        - 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(
            	"john.doe@example.com",
            	{
            		template: "SIGNIN",
            		expiresIn: 100,
            		magiclinkAuthUri: "https://www.google.com",
            		templateVariables: {
            			employeeID: "EMP523",
            			teamName: "Alpha Team",
            			supportEmail: "support@yourcompany.com",
            		},
            	}
            );
        - label: Python SDK
          lang: python
          source: |-
            response = scalekit_client.passwordless.send_passwordless_email(
                email="john.doe@example.com",
                template="SIGNIN",  # or "SIGNUP", "UNSPECIFIED"
                expires_in=100,
                magiclink_auth_uri="https://www.google.com",
                template_variables={
                    "employeeID": "EMP523",
                    "teamName": "Alpha Team",
                    "supportEmail": "support@yourcompany.com",
                },
            )

            # Extract auth request ID from response
            auth_request_id = response[0].auth_request_id
        - label: Go SDK
          lang: go
          source: >-
            templateType := scalekit.TemplateTypeSignin

            response, err :=
            scalekitClient.Passwordless().SendPasswordlessEmail(
                ctx,
                "john.doe@example.com",
                &scalekit.SendPasswordlessOptions{
                    Template:         &templateType,
                    ExpiresIn:        100,
                    MagiclinkAuthUri: "https://www.google.com",
                    TemplateVariables: map[string]string{
                        "employeeID":    "EMP523",
                        "teamName":      "Alpha Team",
                        "supportEmail":  "support@yourcompany.com",
                    },
                },
            )


            if err != nil {
                // Handle error
                return
            }


            authRequestId := response.AuthRequestId
        - label: Java SDK
          lang: java
          source: >-
            TemplateType templateType = TemplateType.SIGNIN;

            Map<String, String> templateVariables = new HashMap<>();

            templateVariables.put("employeeID", "EMP523");

            templateVariables.put("teamName", "Alpha Team");

            templateVariables.put("supportEmail", "support@yourcompany.com");


            SendPasswordlessOptions options = new SendPasswordlessOptions();

            options.setTemplate(templateType);

            options.setExpiresIn(100);

            options.setMagiclinkAuthUri("https://www.example.com");

            options.setTemplateVariables(templateVariables);


            SendPasswordlessResponse response =
            passwordlessClient.sendPasswordlessEmail(
                "john.doe@example.com",
                options
            );


            String 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;

            const verifyResponse = await
            scalekit.passwordless.verifyPasswordlessEmail(

            	// Verification Code (OTP)

            	{ code: "123456" },

            	// Magic Link Token

            	{ linkToken: link_token },

            	authRequestId

            );
        - label: Python SDK
          lang: python
          source: >-
            # Verify with OTP code

            verify_response =
            scalekit_client.passwordless.verify_passwordless_email(
                code="123456",  # OTP code received via email
                auth_request_id=auth_request_id,
            )


            # Verify with magic link token

            verify_response =
            scalekit_client.passwordless.verify_passwordless_email(
                link_token=link_token,  # Magic link token from URL
            )


            # User verified successfully

            user_email = verify_response[0].email
        - label: Go SDK
          lang: go
          source: >-
            // Verify with OTP code

            verifyResponse, err :=
            scalekitClient.Passwordless().VerifyPasswordlessEmail(
                ctx,
                &scalekit.VerifyPasswordlessOptions{
                    Code:          "123456", // OTP code
                    AuthRequestId: authRequestId,
                },
            )


            if err != nil {
                // Handle error
                return
            }


            // Verify with magic link token

            verifyResponse, err :=
            scalekitClient.Passwordless().VerifyPasswordlessEmail(
                ctx,
                &scalekit.VerifyPasswordlessOptions{
                    LinkToken: linkToken, // Magic link token
                },
            )


            if err != nil {
                // Handle error
                return
            }


            // User verified successfully

            userEmail := verifyResponse.Email
        - label: Java SDK
          lang: java
          source: >-
            // Verify with OTP code

            VerifyPasswordlessOptions verifyOptions = new
            VerifyPasswordlessOptions();

            verifyOptions.setCode("123456"); // OTP code

            verifyOptions.setAuthRequestId(authRequestId);


            VerifyPasswordLessResponse verifyResponse =
            passwordlessClient.verifyPasswordlessEmail(verifyOptions);


            // User verified successfully

            String userEmail = verifyResponse.getEmail();


            // Verify with magic link token

            VerifyPasswordlessOptions verifyOptions = new
            VerifyPasswordlessOptions();

            verifyOptions.setLinkToken(linkToken); // Magic link token


            VerifyPasswordLessResponse verifyResponse =
            passwordlessClient.verifyPasswordlessEmail(verifyOptions);


            // User verified successfully

            String 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)
            if err != nil { /* handle err */ }
            _ = 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({
              name: "read:users",
              description: "Allows reading users"
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import CreatePermission

            permission = CreatePermission(
                name="read:users",
                description="Allows reading users"
            )

            scalekit_client.permissions.create_permission(permission=permission)
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Permission().CreatePermission(ctx,
            &rolesv1.CreatePermission{

            	Name:        "read:users",

            	Description: "Allows reading users",

            })

            if err != nil { /* handle err */ }

            _ = resp
        - label: Java SDK
          lang: java
          source: >-
            CreatePermissionResponse res =
            scalekitClient.permissions().createPermission(
                CreatePermissionRequest.newBuilder()
                    .setPermission(
                        CreatePermission.newBuilder()
                            .setName("read:users")
                            .setDescription("Allows reading users")
                            .build()
                    )
                    .build()
            );
      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(
                permission_name="read:users"
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Permission().GetPermission(ctx,
            "read:users")

            if err != nil { /* handle err */ }

            _ = 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", {
              name: "read:users",
              description: "Allows reading user resources"
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import CreatePermission

            scalekit_client.permissions.update_permission(
                permission_name="read:users",
                permission=CreatePermission(
                    name="read:users",
                    description="Allows reading user resources"
                )
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Permission().UpdatePermission(ctx,
            "read:users", &rolesv1.CreatePermission{
                Name:        "read:users",
                Description: "Allows reading user resources",
            })

            if err != nil { /* handle err */ }

            _ = resp
        - label: Java SDK
          lang: java
          source: >-
            UpdatePermissionResponse res =
            scalekitClient.permissions().updatePermission(
                "read:users",
                UpdatePermissionRequest.newBuilder()
                    .setPermission(
                        CreatePermission.newBuilder()
                            .setName("read:users")
                            .setDescription("Allows reading user resources")
                            .build()
                    )
                    .build()
            );
      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(
                permission_name="read:users"
            )
        - label: Go SDK
          lang: go
          source: >-
            err := scalekitClient.Permission().DeletePermission(ctx,
            "read:users")

            if 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)
            if err != nil { /* handle err */ }
            _ = 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({
              name: "admin",
              displayName: "Admin",
              description: "Environment-level role",
              extends: "base_role",                // optional
              permissions: ["read:users"]          // optional
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import CreateRole

            role = CreateRole(
                name="admin",
                display_name="Admin",
                description="Environment-level role",
                extends="base_role",                  # optional
                permissions=["read:users"]           # optional
            )

            scalekit_client.roles.create_role(role=role)
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Role().CreateRole(ctx,
            &rolesv1.CreateRole{

            	Name:        "admin",

            	DisplayName: "Admin",

            	Description: "Environment-level role",

            	Extends:     proto.String("base_role"),      // optional

            	Permissions: []string{"read:users"},        // optional

            })
        - label: Java SDK
          lang: java
          source: |-
            CreateRoleResponse res = scalekitClient.roles().createRole(
                CreateRoleRequest.newBuilder()
                    .setRole(
                        CreateRole.newBuilder()
                            .setName("admin")
                            .setDisplayName("Admin")
                            .setDescription("Environment-level role")
                            // .setExtends("base_role")         // optional
                            // .addPermissions("read:users")    // optional
                            .build()
                    )
                    .build()
            );
      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")
            if err != nil { /* handle err */ }
            _ = 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", {
              displayName: "Admin (Updated)",
              description: "Updated description"
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import UpdateRole

            scalekit_client.roles.update_role(
                role_name="admin",
                role=UpdateRole(
                    display_name="Admin (Updated)",
                    description="Updated description"
                )
            )
        - label: Go SDK
          lang: go
          source: >-
            resp, err := scalekitClient.Role().UpdateRole(ctx, "admin",
            &rolesv1.UpdateRole{
                DisplayName: "Admin (Updated)",
                Description: "Updated description",
            })

            if err != nil { /* handle err */ }

            _ = resp
        - label: Java SDK
          lang: java
          source: |-
            UpdateRoleResponse res = scalekitClient.roles().updateRole(
                "admin",
                UpdateRoleRequest.newBuilder()
                    .setRole(
                        UpdateRole.newBuilder()
                            .setDisplayName("Admin (Updated)")
                            .setDescription("Updated description")
                            .build()
                    )
                    .build()
            );
      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
            await scalekit.role.deleteRole("admin");

            // With reassignment
            await scalekit.role.deleteRole("admin", "member");
        - label: Python SDK
          lang: python
          source: |-
            # Basic delete
            scalekit_client.roles.delete_role(role_name="admin")

            # With reassignment
            scalekit_client.roles.delete_role(
                role_name="admin",
                reassign_role_name="member"
            )
        - label: Go SDK
          lang: go
          source: |-
            // Basic delete
            err := scalekitClient.Role().DeleteRole(ctx, "admin")
            if err != nil { /* handle err */ }

            // With reassignment
            err = scalekitClient.Role().DeleteRole(ctx, "admin", "member")
        - label: Java SDK
          lang: java
          source: |-
            // Basic delete
            scalekitClient.roles().deleteRole("admin");

            // With reassignment
            scalekitClient.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")
            if err != nil {
                // handle error
            }
        - 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")
            if err != nil { /* handle err */ }
            _ = 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")

            if err != nil { /* handle err */ }

            _ = 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(
                role_name="role_admin",
                permission_names=["perm.read", "perm.write"]
            )
        - 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(
                "role_admin",
                AddPermissionsToRoleRequest.newBuilder()
                    .addPermissionNames("perm.read")
                    .addPermissionNames("perm.write")
                    .build()
            );
      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(
                role_name="admin",
                permission_name="read:users"
            )
        - label: Go SDK
          lang: go
          source: >-
            err := scalekitClient.Permission().RemovePermissionFromRole(ctx,
            "admin", "read:users")

            if 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")
            permissions = response.permissions
        - label: Go SDK
          lang: go
          source: >-
            resp, err :=
            scalekitClient.Permission().ListEffectiveRolePermissions(ctx,
            "senior_editor")

            if err != nil {
                // handle error
            }

            permissions := resp.Permissions
        - label: Java SDK
          lang: java
          source: |-
            ListEffectiveRolePermissionsResponse response = scalekitClient.permissions().listEffectiveRolePermissions("senior_editor");
            List<Permission> 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")
            if err != nil { /* handle err */ }
            _ = 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({
              defaultMemberRole: "member"
            });
        - label: Python SDK
          lang: python
          source: |-
            from scalekit.v1.roles.roles_pb2 import UpdateDefaultRolesRequest

            res = scalekit_client.roles.update_default_roles(
                default_roles=UpdateDefaultRolesRequest(
                    default_member_role="member"
                )
            )
        - label: Go SDK
          lang: go
          source: |-
            resp, err := scalekitClient.Role().UpdateDefaultRoles(ctx, "member")
            if err != nil { /* handle err */ }
            _ = resp
        - label: Java SDK
          lang: java
          source: >-
            UpdateDefaultRolesResponse res =
            scalekitClient.roles().updateDefaultRoles(
                UpdateDefaultRolesRequest.newBuilder()
                    .setDefaultMemberRole("member")
                    .build()
            );
      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")

            if err != nil { /* handle err */ }

            _ = 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")

            if err != nil { /* handle err */ }

            _ = 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(
              { pageSize: 100 });
        - label: Python SDK
          lang: python
          source: >-
            # pass empty org to fetch all users in environment

            resp,_ = 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.
              newBuilder().setPageSize(100).build();
            ListUsersResponse 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")
            user = resp.user
        - label: Go SDK
          lang: go
          source: |-
            resp, err := scalekitClient.User().GetUser(ctx, "usr_123456")
            if err != nil {
                // handle error
            }
            user := resp.User
        - label: Java SDK
          lang: java
          source: |-
            GetUserResponse resp = scalekitClient.users().getUser("usr_123456");
            User 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", 
              user_id="usr_123")
        - label: Go SDK
          lang: go
          source: |-
            if err := scalekitClient.User().DeleteUser(ctx, 
              "usr_123"); err != nil {
                panic(err)
            }
        - 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", {
            	userProfile: {
            		firstName: "John",
            		lastName: "Smith",
            	},
            	metadata: {
            		department: "sales",
            	},
            });
        - label: Python SDK
          lang: python
          source: |-
            import os
            from scalekit import ScalekitClient
            from scalekit.v1.users.users_pb2 import UpdateUser
            from scalekit.v1.commons.commons_pb2 import UserProfile
            scalekit_client = ScalekitClient(
                env_url=os.getenv("SCALEKIT_ENV_URL"),
                client_id=os.getenv("SCALEKIT_CLIENT_ID"),
                client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
            )
            update_user = UpdateUser(
                user_profile=UserProfile(
                    first_name="John",
                    last_name="Smith"
                ),
                metadata={"department": "sales"}
            )
            scalekit_client.users.update_user(organization_id="org_123", 
              user=update_user)
        - label: Go SDK
          lang: go
          source: |-
            upd := &usersv1.UpdateUser{
                UserProfile: &usersv1.UpdateUserProfile{
                    FirstName: "John",
                    LastName:  "Smith",
                },
                Metadata: map[string]string{
                    "department": "sales",
                },
            }
            scalekitClient.User().UpdateUser(ctx, "usr_123", upd)
        - label: Java SDK
          lang: java
          source: |-
            UpdateUser upd = UpdateUser.newBuilder()
                    .setUserProfile(
                      UpdateUserProfile.newBuilder()
                            .setFirstName("John")
                            .setLastName("Smith")
                            .build())
                    .putMetadata("department", "sales")
                    .build();
            UpdateUserRequest updReq = UpdateUserRequest.
              newBuilder().setUser(upd).build();
            users.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
            const res = await scalekit.session.getUserSessions("user_123");

            // With pagination and filtering
            const res = await scalekit.session.getUserSessions("user_123", {
              pageSize: 10,
              pageToken: "next_page_token",
              filter: {
                status: ["ACTIVE"],
                startTime: new Date("2024-01-01"),
                endTime: new Date("2024-12-31")
              }
            });
        - label: Python SDK
          lang: python
          source: >-
            # Basic usage

            res = scalekit_client.sessions.get_user_sessions(user_id="user_123")


            # With pagination and filtering

            from google.protobuf.timestamp_pb2 import Timestamp

            from datetime import datetime


            start_time = Timestamp()

            start_time.FromDatetime(datetime(2024, 1, 1))

            end_time = Timestamp()

            end_time.FromDatetime(datetime(2024, 12, 31))


            filter_obj = scalekit_client.sessions.create_session_filter(
                status=["ACTIVE"], start_time=start_time, end_time=end_time
            )

            res = scalekit_client.sessions.get_user_sessions(
                user_id="user_123", page_size=10, page_token="next_page_token", filter=filter_obj
            )
        - label: Go SDK
          lang: go
          source: >-
            // Basic usage

            resp, err := scalekitClient.Session().GetUserSessions(ctx,
            "user_123", 0, "", nil)

            if err != nil { /* handle err */ }


            // With pagination and filtering

            // import "time", sessionsv1 "...",
            "google.golang.org/protobuf/types/known/timestamppb"

            startTime, _ := time.Parse(time.RFC3339, "2024-01-01T00:00:00Z")

            endTime, _ := time.Parse(time.RFC3339, "2024-12-31T23:59:59Z")

            filter := &sessionsv1.UserSessionFilter{
                Status:    []string{"ACTIVE"},
                StartTime: timestamppb.New(startTime),
                EndTime:   timestamppb.New(endTime),
            }

            resp, err := scalekitClient.Session().GetUserSessions(ctx,
            "user_123", 10, "next_page_token", filter)

            if err != nil { /* handle err */ }
        - label: Java SDK
          lang: java
          source: >-
            // Basic usage

            UserSessionDetails res =
            scalekitClient.sessions().getUserSessions("user_123", null, null,
            null);


            // With pagination and filtering

            // import UserSessionFilter, Timestamp, Instant

            UserSessionFilter filter = UserSessionFilter.newBuilder()
                .addStatus("ACTIVE")
                .setStartTime(Timestamp.newBuilder().setSeconds(Instant.parse("2024-01-01T00:00:00Z").getEpochSecond()).build())
                .setEndTime(Timestamp.newBuilder().setSeconds(Instant.parse("2024-12-31T23:59:59Z").getEpochSecond()).build())
                .build();
            UserSessionDetails 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")

            if err != nil { /* handle err */ }

            _ = 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")

            if err != nil { /* handle err */ }

            _ = 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")

            if err != nil { /* handle err */ }

            _ = 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(
              "wac_123",
              "Work Laptop Passkey"
            );
        - label: Python SDK
          lang: python
          source: |-
            res = scalekit_client.webauthn.update_credential(
                credential_id="wac_123",
                display_name="Work Laptop Passkey"
            )
        - label: Go SDK
          lang: go
          source: |-
            resp, err := scalekitClient.WebAuthn().UpdateCredential(
                ctx,
                "wac_123",
                "Work Laptop Passkey",
            )
            if err != nil { /* handle err */ }
            _ = resp
        - label: Java SDK
          lang: java
          source: |-
            UpdateCredentialResponse res = scalekitClient.webauthn()
                .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`.

      <!-- ## Organization Attributes

      | Attribute Name             | Attribute Description                                                                                                                        |
      | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
      | `id`<br>_string_           | Unique ID of an Organization. Required for all API operations against this organization.                                                     |
      | `display_name`<br>_string_ | Name of the Organization                                                                                                                     |
      | `create_time`<br>_string_  | Creation timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.<br>Example: `2011-10-05T14:48:00.000Z`                      |
      | `update_time`<br>_string_  | Last update timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.<br>Example: `2021-10-05T14:48:00.000Z`                   |
      | `external_id`<br>_string_  | Your system's unique ID for this organization. You can use this to fetch Organization and Connection details without storing Scalekit's IDs. |
      | `metadata`<br>_object_     | Additional organization information stored as JSON.<br>Example: `{"key":"value"}`                                                            |
      | `region_code`<br>_string_  | Data center region where organization data is stored. Currently always returns `US`.                                                         | -->
    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:


      - 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.

      - 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).
    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)

            At 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://<domain>)
            At 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.

        ACTIVE secrets can be used for authentication while INACTIVE secrets
        cannot.

         - 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:
            - <next_page_token>
        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:
            - <prev_page_token>
        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. 

            Possible values: 

            - `jit_using_sso` (Just-in-time provisioning during SSO login)

            - `allowed_email_domain` (User joined via allowed email domain
            matching)

            - `org_creator` (User created the organization)

            - `direct_provision` (User was directly provisioned via API or SCIM)

            - `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
         - EXPIRED: Access token has expired and needs refresh
         - PENDING_AUTH: Account awaiting user authorization (re-auth initiated)
         - PENDING_VERIFICATION: OAuth complete; awaiting user identity verification
        before 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
         - API_KEY: Static API key authentication
         - BASIC_AUTH: HTTP Basic Authentication (username/password)
         - BEARER_TOKEN: Bearer token authentication
         - CUSTOM: Custom authentication mechanism
         - 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.

        When present in ErrorInfo, clients should surface these links to help

        developers resolve the error. For example, a missing required field
        error

        may 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

        or providing other forms of feedback.
      type: object
      properties:
        request_id:
          description: >-
            An opaque string that should only be interpreted by the service
            generating

            it. 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

            stack 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.

            For example, updating a cloud project may require the `writer`
            permission

            on 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
        syntactic 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
         - 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:
            - <next_page_token>
        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:
            - <prev_page_token>
        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.


            * You may include up to 30 key-value pairs.

            * The following variable names are reserved by the system and cannot
            be supplied: `otp`, `expiry_time_relative`, `link`, `expire_time`,
            `expiry_time`.

            * Every variable referenced in your email template must be included
            as a key-value pair.


            Use 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

        `Value` type union.


        The 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.

            - ALLOWED_EMAIL_DOMAIN: trusted domain used to suggest the
            organization in the organization switcher during sign-in/sign-up.

            - ORGANIZATION_DOMAIN: SSO discovery domain used to route users to
            the correct SSO provider and enforce SSO.
          $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 events
            - 'organization.created'
            - 'organization.updated'
            - 'organization.deleted'
            - 'organization.sso_created'
            - 'organization.sso_deleted'
            - 'organization.sso_enabled'
            - 'organization.sso_disabled'
            # User events
            - 'user.signup'
            - 'user.login'
            - 'user.logout'
            - 'user.organization_invitation'
            - 'user.organization_membership_created'
            - 'user.organization_membership_updated'
            - 'user.organization_membership_deleted'
            # Directory events
            - '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 events
            - 'role.created'
            - 'role.updated'
            - 'role.deleted'
            # Permission events
            - '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 Events
  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:
                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:
                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:
                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 Events
  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:
                  metadata:
                  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:
                    email_verified: true
                    external_identities:
                    family_name: 'doe'
                    gender: ''
                    given_name: 'John'
                    groups:
                    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:
                    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:
                    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:
                  idle_expires_at: '2025-12-16T12:04:41.737395Z'
                  last_active_at: '2025-12-09T12:04:41.747206Z'
                  logout_at:
                  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:
                    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:
                    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:
                  idle_expires_at: '2025-12-16T12:04:41.737395Z'
                  last_active_at: '2025-12-09T12:04:41.747206Z'
                  logout_at:
                  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

  # Organization Membership Events
  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:
                  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:
                    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:
                    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:
                  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:
                    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:
                    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:
                  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:
                    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:
                  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:
                    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

  # Directory Connection Events
  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

  # Directory User Events
  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: '<id from IDP>'
                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: '<scim_external_id>'
                preferred_username: '<idp_user_name>'
                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: '<scim_external_id>'
                email: 'john.doe@example.com'
              display_name: 'Directory User Deleted'
      responses:
        '200':
          description: Webhook received successfully

  # Directory Group Events
  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:
                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: '<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

  # Enterprise SSO Events
  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 Events
  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 Events
  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 Events
  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
