Keboola Organizations API

openapi: 3.2.0
info:
  title: Keboola Connection Management Organizations API
  description: 'The Keboola Connection Management API covers all tasks required for managing

    projects, plus super-admin features for controlling and monitoring Keboola Connection.


    ## Projects management

    * Create, modify and delete maintainers, organizations and projects

    * Move projects between organizations

    * Define project limits

    * Provision storage backends

    * Access project management activity log


    ## Projects monitoring

    * Monitoring of projects across organizations and maintainers


    ## Super user control and monitoring

    * UI release and deployment

    * Components management

    * Final project delete

    * Workers start/shutdown, etc.


    ## Authentication

    The API authenticates with a personal access token sent in the `X-KBC-ManageApiToken`

    header. Tokens can be created in

    [Account Settings](https://connection.keboola.com/admin/account/change-password)

    in Keboola Connection. A token is tied to an administrator and inherits that

    administrator''s permissions; when the administrator is disabled or deleted, all

    their tokens become invalid.


    ```

    curl -H "X-KBC-ManageApiToken: USER_TOKEN" https://connection.keboola.com/manage/tokens/verify

    ```


    ## Token types

    | Type  | Tied to a user | Token string visible only on create | Description |

    | ----- | -------------- | ----------------------------------- | ----------- |

    | user  | Yes            | Yes                                 | Full access to maintainers, organizations and projects the user can see. |

    | super | No             | Yes                                 | KBC management. Scopes such as `super_ui_deploy`, `super_monitoring` etc. can be limited per-token. |


    Legacy Apiary reference: see the

    [Manage API blueprint](https://github.com/keboola/connection/blob/master/Package/ManageApiPhpClient/apiary.apib)

    for the historical document this OpenAPI spec is migrating from.

    '
  version: '1.0'
servers:
- url: https://connection.keboola.com
  description: AWS US East
- url: https://connection.eu-central-1.keboola.com
  description: AWS EU Central
- url: https://connection.north-europe.azure.keboola.com
  description: Azure North Europe
- url: https://connection.east-us-2.azure.keboola-testing.com
  description: Azure Testing
security:
- StorageKey: []
- ManageKey: []
- BearerAuth: []
tags:
- name: Organizations
  description: Manage organizations, their members and invitations.
paths:
  /manage/maintainers/{id}/organizations:
    get:
      tags:
      - Organizations
      summary: List maintainer's organizations
      description: Returns all organizations belonging to the specified maintainer.
      operationId: get_/manage/maintainers/{id}/organizations::MaintainerListOrganizationsAction
      parameters:
      - name: id
        in: path
        description: Identifier of the maintainer.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 1
      responses:
        '200':
          description: List of organizations.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                      example: 123
                    name:
                      type: string
                      example: sample org
                    created:
                      type: string
                      format: date-time
                      example: '2014-11-11T08:40:51.620Z'
                    allowAutoJoin:
                      type: boolean
                      example: true
                    crmId:
                      type:
                      - string
                      - 'null'
                      example: '6232456'
                    activityCenterProjectId:
                      type:
                      - integer
                      - 'null'
                      example: 123
                    mfaRequired:
                      type: boolean
                      example: false
                  type: object
              example:
              - id: 123
                name: sample org
                created: '2014-11-11T08:40:51.620Z'
                allowAutoJoin: true
                crmId: '6232456'
                activityCenterProjectId: 123
                mfaRequired: false
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the maintainer.
        '404':
          description: Returned when the maintainer does not exist.
    post:
      tags:
      - Organizations
      summary: Create an organization
      description: Creates a new organization within the specified maintainer.
      operationId: post_/manage/maintainers/{id}/organizations::MaintainerCreateOrganizationAction
      parameters:
      - name: id
        in: path
        description: Identifier of the parent maintainer. The created organization will be assigned to this maintainer.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMaintainerOrganizationRequest'
            example:
              name: POC
              crmId: '234'
      responses:
        '200':
          description: Organization created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
        '400':
          description: Returned when provided parameters are invalid.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to create organizations.
        '404':
          description: Returned when the maintainer does not exist.
  /manage/organizations/{id}/users:
    get:
      tags:
      - Organizations
      summary: List organization users
      description: Returns all administrators of the organization specified by its ID.
      operationId: get_/manage/organizations/{id}/users::OrganizationListAdministratorsAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 1
      responses:
        '200':
          description: List of organization users.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                      example: 23423
                    name:
                      type: string
                      example: Martin Halamicek
                    email:
                      type: string
                      example: martin@keboola.com
                  type: object
              example:
              - id: 23423
                name: Martin Halamicek
                email: martin@keboola.com
        '400':
          description: Returned when MFA is required.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization does not exist.
    post:
      tags:
      - Organizations
      summary: Add a User to organization
      description: Either `id` or `email` of a user must be set. If the email is not associated with a user, a new account is created and an invitation is sent.
      operationId: post_/manage/organizations/{id}/users::OrganizationAddAdministratorAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                id:
                  description: User ID.
                  type:
                  - integer
                  - 'null'
                  example: 7234
                email:
                  description: User email.
                  type:
                  - string
                  - 'null'
                  format: email
                  example: martin@keboola.com
              type: object
            example:
              email: martin@keboola.com
      responses:
        '200':
          description: User added to organization successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '400':
          description: Returned when the provided parameters are invalid or the user is already a member.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to add administrators, or when MFA is required.
        '404':
          description: Returned when the organization does not exist.
  /manage/organizations/{id}/invitations/{invitationId}:
    get:
      tags:
      - Organizations
      summary: Organization invitation detail
      description: Returns detail of the invitation specified by its ID for the given organization.
      operationId: get_/manage/organizations/{id}/invitations/{invitationId}::OrganizationGetInvitationAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      - name: invitationId
        in: path
        description: Identifier of the invitation.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 113
      responses:
        '200':
          description: Invitation detail response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitationDetailResponse'
              example:
                id: 113
                created: 2018-07-10T10:50:00+0200
                user:
                  id: 125
                  name: test user 3
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
        '400':
          description: Returned when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization or invitation does not exist.
    delete:
      tags:
      - Organizations
      summary: Cancel organization invitation
      description: Cancels the invitation specified by its ID for the given organization.
      operationId: delete_/manage/organizations/{id}/invitations/{invitationId}::OrganizationCancelInvitationAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      - name: invitationId
        in: path
        description: Identifier of the invitation.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 113
      responses:
        '204':
          description: Invitation cancelled successfully.
        '400':
          description: Returned when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization or invitation does not exist.
  /manage/organizations/{id}/invitations:
    get:
      tags:
      - Organizations
      summary: List organization invitations
      description: Returns all invitations for the organization specified by its ID.
      operationId: get_/manage/organizations/{id}/invitations::OrganizationListInvitationsAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      responses:
        '200':
          description: List of organization invitations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationInvitationDetailResponse'
              example:
              - id: 112
                created: 2018-07-10T10:45:11+0200
                user:
                  id: 124
                  name: test user 2
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
              - id: 113
                created: 2018-07-10T10:50:00+0200
                user:
                  id: 125
                  name: test user 3
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
        '400':
          description: Returned when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization does not exist.
    post:
      tags:
      - Organizations
      summary: Invite a user to a organization
      description: Only members of the organization can invite other users.
      operationId: post_/manage/organizations/{id}/invitations::OrganizationCreateInvitationAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - email
              properties:
                email:
                  description: Email of an invited user.
                  type: string
                  format: email
                  example: martin@keboola.com
              type: object
            example:
              email: martin@keboola.com
      responses:
        '201':
          description: Invitation created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationInvitationDetailResponse'
              example:
                id: 113
                created: 2018-07-10T10:50:00+0200
                user:
                  id: 125
                  name: test user 3
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
        '400':
          description: Returned when the provided parameters are invalid.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization does not exist.
        '422':
          description: Returned when the provided email address is invalid.
  /manage/organizations/{id}:
    get:
      tags:
      - Organizations
      summary: Retrieve an organization
      description: 'To access token needs to be superuser, member of the organization, member of the maintainer or application token with

        scope `organizations:read`.'
      operationId: get_/manage/organizations/{id}::OrganizationDetailAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      responses:
        '200':
          description: Organization detail response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationDetailResponse'
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization, or when MFA is required.
        '404':
          description: Returned when the organization does not exist.
    delete:
      tags:
      - Organizations
      summary: Delete an organization
      description: Deletes the organization specified by its ID.
      operationId: delete_/manage/organizations/{id}::OrganizationDeleteAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      responses:
        '204':
          description: Organization deleted successfully.
        '400':
          description: Returned when the organization cannot be deleted (e.g. it still has projects, or MFA is required).
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization does not exist.
    patch:
      tags:
      - Organizations
      summary: Update an organization
      description: Partial update of an organization.
      operationId: patch_/manage/organizations/{id}::OrganizationUpdateAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  description: Organization name.
                  type: string
                  example: POC
                maintainerId:
                  description: Assign the organization to another maintainer.
                  type: integer
                  example: 4
                allowAutoJoin:
                  description: Set whether superAdmins need approval to join the organization's projects (default `true`).
                  type: boolean
                  example: true
                crmId:
                  description: Set CRM ID. Only maintainer members and superadmins can change this.
                  type:
                  - string
                  - 'null'
                  example: '123456'
                activityCenterProjectId:
                  description: Set ActivityCenter ProjectId. Only maintainer members and superadmins can change this.
                  type:
                  - integer
                  - 'null'
                  example: 123
                mfaRequired:
                  description: Toggle whether all members of or organization and its projects must have enabled multi-factor authentication (default `false`).
                  type: boolean
                  example: false
              type: object
            example:
              name: POC
              crmId: '123456'
      responses:
        '200':
          description: Organization updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationWithProjectsResponse'
              example:
                id: 123
                name: POC
                created: 2015-10-02T11:03:44+0200
                allowAutoJoin: true
                crmId: '123456'
                activityCenterProjectId: 123
                mfaRequired: false
                projects:
                - id: 123
                  name: Demo
                  created: '2014-11-11T08:40:51.620Z'
        '400':
          description: Returned when the provided parameters are invalid.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to update the organization.
        '404':
          description: Returned when the organization does not exist.
  /manage/organizations/{id}/metadata/{metadataId}:
    delete:
      tags:
      - Organizations
      summary: Remove organization metadata
      description: Only organization members, members of the maintainer and super admins can delete metadata.
      operationId: delete_/manage/organizations/{id}/metadata/{metadataId}::OrganizationDeleteMetadataAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      - name: metadataId
        in: path
        description: Identifier of the metadata entry.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 123
      responses:
        '204':
          description: Metadata deleted successfully.
        '400':
          description: Returned when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization or metadata entry does not exist.
  /manage/organizations/{id}/join-organization:
    post:
      tags:
      - Organizations
      summary: Join an organization
      description: If the organization allows autojoin (`allowAutoJoin` attribute is set to `true`), all members of its maintainer and superadmins are allowed to join the organization.
      operationId: post_/manage/organizations/{id}/join-organization::OrganizationJoinAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      responses:
        '204':
          description: Successfully joined the organization.
        '400':
          description: Returned when the admin is already a member or MFA is required.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to join the organization.
        '404':
          description: Returned when the organization does not exist.
  /manage/organizations:
    get:
      tags:
      - Organizations
      summary: List organizations
      description: Lists all organizations the user is part of. If authorized with application token with scope `organizations:read`, all organizations are listed.
      operationId: get_/manage/organizations::OrganizationListAction
      responses:
        '200':
          description: Organizations list response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationsListResponse'
              example:
              - id: 123
                name: Some Organization
                created: '2014-11-11T08:40:51.620Z'
                allowAutoJoin: true
                crmId: '6232456'
                activityCenterProjectId: 123
                mfaRequired: false
                maintainer:
                  id: 4
                  name: Some Maintainer
                  created: 2025-04-28T09:43:21+0200
                  defaultConnectionMysqlId: null
                  defaultConnectionSnowflakeId: 1
                  defaultConnectionSynapseId: null
                  defaultConnectionExasolId: null
                  defaultConnectionBigqueryId: null
                  defaultConnectionTeradataId: null
                  defaultFileStorageId: 1
                  zendeskUrl: null
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to list organizations.
  /manage/organizations/{id}/metadata:
    get:
      tags:
      - Organizations
      summary: List organization Metadata
      description: Only members of the maintainer, members of organization and super admins can list metadata.
      operationId: get_/manage/organizations/{id}/metadata::OrganizationListMetadataAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      responses:
        '200':
          description: List of organization metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                      example: 123
                    provider:
                      type: string
                      example: user
                    timestamp:
                      type: string
                      example: 2021-02-17T15:05:21+0100
                    key:
                      type: string
                      example: KBC.SomeEnity.metadataKey
                    value:
                      type: string
                      example: Some value
                  type: object
              example:
              - id: 123
                provider: user
                timestamp: 2021-02-17T15:05:21+0100
                key: KBC.SomeEnity.metadataKey
                value: Some value
              - id: 124
                provider: user
                timestamp: 2021-02-17T15:05:21+0100
                key: someMetadataKey
                value: Some value
        '400':
          description: Returned when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization does not exist.
    post:
      tags:
      - Organizations
      summary: Set organization metadata
      description: 'Sets multiple metadata with one call. If the given key and provider combination already exist

        for the organization, the data will be updated with the new value and timestamp.

        Only organization members, members of the maintainer and super admins can change metadata.'
      operationId: post_/manage/organizations/{id}/metadata::OrganizationSetMetadataAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationMetadataRequest'
            example:
              provider: user
              metadata:
              - key: KBC.SomeEnity.metadataKey
                value: Some value
              - key: someMetadataKey
                value: Some value
      responses:
        '201':
          description: Metadata set successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                      example: 123
                    provider:
                      type: string
                      example: user
                    timestamp:
                      type: string
                      example: 2021-02-17T15:05:21+0100
                    key:
                      type: string
                      example: KBC.SomeEnity.metadataKey
                    value:
                      type: string
                      example: Some value
                  type: object
              example:
              - id: 123
                provider: user
                timestamp: 2021-02-17T15:05:21+0100
                key: KBC.SomeEnity.metadataKey
                value: Some value
              - id: 124
                provider: user
                timestamp: 2021-02-17T15:05:21+0100
                key: someMetadataKey
                value: Some value
        '400':
          description: Returned when the provided metadata is invalid, or when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization.
        '404':
          description: Returned when the organization does not exist.
  /manage/organizations/{id}/projects-users:
    get:
      tags:
      - Organizations
      summary: List project users in organization
      description: List of all users who are members of at least one project in the organization. Only members of the organization can get this list.
      operationId: get_/manage/organizations/{id}/projects-users::OrganizationListProjectsUsersAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 1
      responses:
        '200':
          description: List of users across projects in the organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                      example: 123
                    name:
                      type: string
                      example: test user
                    email:
                      type: string
                      example: martin@keboola.com
                  type: object
              example:
              - id: 123
                name: test user
                email: martin@keboola.com
              - id: 125
                name: test user 3
                email: spam@keboola.com
        '400':
          description: Returned when the organization requires MFA and the current user does not have MFA enabled.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to list project users.
        '404':
          description: Returned when the organization does not exist.
  /manage/organizations/{id}/users/{userId}:
    delete:
      tags:
      - Organizations
      summary: Remove a user from organization
      description: Removes the specified user from the organization.
      operationId: delete_/manage/organizations/{id}/users/{userId}::OrganizationRemoveAdministratorAction
      parameters:
      - name: id
        in: path
        description: Identifier 

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keboola/refs/heads/main/openapi/keboola-organizations-api-openapi.yml