openapi: 3.0.3
info:
  title: Organizations
  description: >-
    In business-to-business (B2B) use cases, organizations represent your
    business customers and partners. You can manage these organizations, and
    delegate access so they can manage their own membership. Using member APIs,
    organizations can manage the profiles of their users, control which apps
    they can access, and federate login to those apps using their own SAML-based
    identity providers.
  version: ''
servers:
  - url: https://api.sbx.transmitsecurity.io/cis
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/cis
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/cis
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/cis
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/cis
    description: Production environment (AU)
security: []
paths:
  /v1/organizations:
    post:
      operationId: createOrganization
      summary: Create organization
      description: >-
        Create an organization that represents your business customer or
        partner. This should be called from the backend, using an admin access
        token (generated by a management app). <br><br>**Required permissions**:
        `organizations:create`, `orgs:create`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateOrganizationInput'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                title: ApiCreatedResponse-createOrganization
                type: object
                required:
                  - result
                description: Organization created
                properties:
                  result:
                    $ref: '#/components/schemas/ApiOrganization'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifierIsTakenHttpError'
      security:
        - AdminAccessToken: []
    get:
      operationId: getAllOrganizations
      summary: Get organizations
      description: >-
        Retrieve a list of all organizations. This should be called from the
        backend, using an admin access token (generated by a management app).
        <br><br>**Required permissions**: `organizations:read`, `orgs:read`,
        `organizations:list`, `orgs:list`.
      parameters:
        - name: name
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAllOrganizations
                type: object
                required:
                  - result
                description: List of organizations
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiOrganization'
      security:
        - AdminAccessToken: []
  /v1/organizations/{organization_id}:
    get:
      operationId: getOrganization
      summary: Get organization by ID
      description: >-
        Retrieve an organization by ID. This should be called from the backend,
        using an admin access token (generated by a management app).
        <br><br>**Required permissions**: `organizations:read`, `orgs:read`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization to retrieve
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getOrganization
                type: object
                required:
                  - result
                description: Organization information
                properties:
                  result:
                    $ref: '#/components/schemas/ApiOrganization'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
    put:
      operationId: updateOrganization
      summary: Update organization
      description: >-
        Update an organization's basic configuration. This should be called from
        the backend, using an admin access token (generated by a management
        app). <br><br>**Required permissions**: `organizations:edit`,
        `orgs:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateOrganizationInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-updateOrganization
                type: object
                required:
                  - result
                description: Updated organization
                properties:
                  result:
                    $ref: '#/components/schemas/ApiOrganization'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
    delete:
      operationId: deleteOrganization
      summary: Delete organization
      description: >-
        Delete an organization. This should be called from the backend, using an
        admin access token (generated by a management app). <br><br>**Required
        permissions**: `organizations:delete`, `orgs:delete`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: The ID of the organization that should be deleted
          schema:
            type: string
      responses:
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
  /v1/organizations/name/{organization_name}:
    get:
      operationId: getOrganizationByName
      summary: Get organization by name
      description: >-
        Retrieve an organization by name. This should be called from the
        backend, using an admin access token (generated by a management app).
        <br><br>**Required permissions**: `organizations:read`, `orgs:read`.
      parameters:
        - name: organization_name
          required: true
          in: path
          description: Name of the organization to retrieve
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getOrganizationByName
                type: object
                required:
                  - result
                description: Organization information
                properties:
                  result:
                    $ref: '#/components/schemas/ApiOrganization'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
  /v1/organizations/{organization_id}/apps:
    put:
      operationId: addAppsToOrganization
      summary: Add apps to organization
      description: >-
        Add apps to the organization so its members can access them. If the
        organization already has apps, this can be used to add additional ones.
        This should be called from the backend, using an admin access token
        (generated by a management app). <br><br>**Required permissions**:
        `organizations:edit`, `orgs:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: The ID of the organization that should be updated
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAppIds'
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
    delete:
      operationId: removeAppsFromOrganization
      summary: Remove apps from organization
      description: >-
        Remove apps from the organization so its members cannot access them.
        This should be called from the backend, using an admin access token
        (generated by a management app). <br><br>**Required permissions**:
        `organizations:edit`, `orgs:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: The ID of the organization that should be updated
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiAppIds'
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - AdminAccessToken: []
  /v1/organizations/{organization_id}/logo:
    post:
      operationId: uploadLogo
      summary: Upload organization logo
      description: >-
        Upload the organization logo and update the logo URL in the database.
        This should be called from the backend, using an admin access token
        (generated by a management app). <br><br>**Required permissions**:
        `organizations:edit`, `orgs:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization to upload the logo for
          schema:
            type: string
      requestBody:
        required: true
        description: Logo image
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LogoUploadDto'
      responses:
        '202':
          description: ''
      security:
        - AdminAccessToken: []
  /v1/organizations/{organization_id}/applications/{app_id}/managed-organizations:
    post:
      operationId: createManagedOrganization
      summary: Create managed organization
      description: >-
        Create a managed organization in context of a specific app. This should
        be called from the backend, using an admin access token (generated by a
        management app) or an organization admin access token.
        <br><br>**Required permissions**: `organizations:create`, `orgs:create`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: The ID of the organization that creates the managed organization
          schema:
            type: string
        - name: app_id
          required: true
          in: path
          description: ID of application
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateManagedOrganizationInput'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                title: ApiCreatedResponse-createManagedOrganization
                type: object
                required:
                  - result
                description: Managed organization created
                properties:
                  result:
                    $ref: '#/components/schemas/ApiOrganization'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifierIsTakenHttpError'
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/organizations/{organization_id}/role-groups/set:
    post:
      operationId: setAssignedRoleGroups
      summary: Set org's role groups
      description: >-
        Update the role groups of the organization for a specific application,
        which will replace any existing role groups for the organization. These
        role groups must first be created for the application. Once added to the
        organization, roles that belong to these role groups can be assigned to
        members of the organization to control their access to the application.
        <br><br>**Required permissions**: `organizations:edit`, `orgs:edit`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to set the roles to
          schema:
            type: string
        - name: organization_id
          required: true
          in: path
          description: ID of the organization to set the roles to
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiRoleGroupIds'
      responses:
        '202':
          description: ''
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/organizations/{organization_id}/role-groups:
    get:
      operationId: getAssignedRoleGroups
      summary: Get org's role groups
      description: >-
        Retrieves all role groups that were added to the organization for a
        specific application. Roles that belong to these role groups can be
        assigned to members of the organization to control their access to the
        application. <br><br>**Required permissions**: `organizations:read`,
        `orgs:read`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application to assign the roles to
          schema:
            type: string
        - name: organization_id
          required: true
          in: path
          description: ID of the organization to assign the roles to
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAssignedRoleGroups
                type: object
                required:
                  - result
                description: ''
                properties:
                  result:
                    $ref: '#/components/schemas/RoleGroupsAndDefaultOrgRolesDto'
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/organizations/{organization_id}/roles-and-groups/set:
    post:
      operationId: setAssignedRolesAndGroups
      summary: Set org's roles and role groups
      description: >-
        Update the roles and role groups of the organization for a specific
        application, which will replace any existing assignments. These roles
        and role groups must first be created for the application. Once added to
        the organization, roles that belong to these role groups or are directly
        assigned can be assigned to members of the organization to control their
        access to the application. <br><br>**Required permissions**:
        `organizations:edit`, `orgs:edit`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application
          schema:
            type: string
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RolesAndRoleGroupsInputDto'
      responses:
        '202':
          description: ''
      security:
        - AdminAccessToken: []
  /v1/applications/{app_id}/organizations/{organization_id}/roles-and-groups:
    get:
      operationId: getAssignedRolesAndGroups
      summary: Get org's roles and role groups
      description: >-
        Retrieves all roles and role groups that were added to the organization
        for a specific application. Roles that belong to these role groups or
        are directly assigned can be assigned to members of the organization to
        control their access to the application. <br><br>**Required
        permissions**: `organizations:read`, `orgs:read`.
      parameters:
        - name: app_id
          required: true
          in: path
          description: ID of the application
          schema:
            type: string
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getAssignedRolesAndGroups
                type: object
                required:
                  - result
                description: ''
                properties:
                  result:
                    $ref: '#/components/schemas/RolesAndRoleGroupsDto'
      security:
        - AdminAccessToken: []
components:
  schemas:
    ApiCreateOrganizationInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the organization
        domain:
          type: string
          description: Domain of the organization
          deprecated: true
        domains:
          description: Domains of the organization
          type: array
          items:
            type: string
        app_ids:
          description: A list of applications the organization can access
          type: array
          items:
            type: string
        enabled:
          type: boolean
          description: Indicates if the organization is currently enabled
        alias_name:
          type: string
          description: Alias name of the organization
      required:
        - name
        - domain
        - domains
        - app_ids
    BadRequestHttpError:
      type: object
      properties:
        message:
          example: Bad request
          type: array
          items:
            type: string
        error_code:
          type: number
          example: 400
      required:
        - message
        - error_code
    IdentifierIsTakenHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
        ts_error_code:
          type: string
      required:
        - message
        - error_code
        - ts_error_code
    ApiOrganization:
      type: object
      properties:
        organization_id:
          type: string
          description: ID of the organization
        app_ids:
          description: A list of applications the organization can access
          type: array
          items:
            type: string
        name:
          type: string
          description: Name of the organization
        domain:
          type: string
          description: Domain of the organization
          deprecated: true
        domains:
          description: Domains of the organization
          type: array
          items:
            type: string
        created_at:
          type: number
          description: Date the organization was created in the tenant
        updated_at:
          type: number
          description: Date the organization was last updated
        enabled:
          type: boolean
          description: Indicates if the organization is currently enabled
        managed_organizations_by_app:
          type: object
          description: Mapping of app IDs to managed organization IDs assigned to this app
          additionalProperties:
            type: array
            items:
              type: string
        managing_organization_id:
          type: string
          description: ID of the managing organization
        logo_url:
          type: string
          description: The URL of the organization's logo
        alias_name:
          type: string
          description: Alias name of the organization
      required:
        - organization_id
        - app_ids
        - name
        - domain
        - enabled
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
        - message
        - error_code
    ApiUpdateOrganizationInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the organization
        domain:
          type: string
          description: Domain of the organization
          deprecated: true
        domains:
          description: Domains of the organization
          type: array
          items:
            type: string
        enabled:
          type: boolean
          description: Indicates if the organization is currently enabled
        alias_name:
          type: string
          description: Alias name of the organization
    ApiAppIds:
      type: object
      properties:
        app_ids:
          description: A list of applications to add the organization to
          type: array
          items:
            type: string
      required:
        - app_ids
    LogoUploadDto:
      type: object
      properties:
        logo:
          type: string
          format: binary
      required:
        - logo
    ApiCreateManagedOrganizationInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the organization
        domain:
          type: string
          description: Domain of the organization
          deprecated: true
        domains:
          description: Domains of the organization
          type: array
          items:
            type: string
        enabled:
          type: boolean
          description: Indicates if the organization is currently enabled
        alias_name:
          type: string
          description: Alias name of the managed organization
      required:
        - name
        - domain
        - domains
    ApiRoleGroupIds:
      type: object
      properties:
        role_group_ids:
          description: Role group ids
          type: array
          items:
            type: string
      required:
        - role_group_ids
    RoleGroupsAndDefaultOrgRolesDto:
      type: object
      properties:
        role_groups:
          description: Role groups
          type: array
          items:
            $ref: '#/components/schemas/ApiRoleGroup'
        default_organization_roles:
          description: Default organization roles
          type: array
          items:
            $ref: '#/components/schemas/ApiRole'
      required:
        - role_groups
        - default_organization_roles
    RolesAndRoleGroupsInputDto:
      type: object
      properties:
        role_group_ids:
          description: Role group ids
          type: array
          items:
            type: string
        role_ids:
          description: Role ids
          type: array
          items:
            type: string
    RolesAndRoleGroupsDto:
      type: object
      properties:
        role_groups:
          description: Role groups
          type: array
          items:
            $ref: '#/components/schemas/ApiRoleGroup'
        default_organization_roles:
          description: Default organization roles
          type: array
          items:
            $ref: '#/components/schemas/ApiRole'
        roles:
          description: Assigned roles
          type: array
          items:
            $ref: '#/components/schemas/ApiRole'
      required:
        - role_groups
        - default_organization_roles
        - roles
    ApiRoleGroup:
      type: object
      properties:
        group_id:
          type: string
          description: Group ID
        name:
          type: string
          description: Group name
        description:
          type: string
          description: Group description
        roles:
          description: Group's roles
          type: array
          items:
            $ref: '#/components/schemas/ApiRole'
        display_name:
          type: string
          description: Role group's display name
      required:
        - group_id
        - name
        - roles
    ApiRole:
      type: object
      properties:
        role_id:
          type: string
          description: Role ID
        role_name:
          type: string
          description: Role name
        permissions:
          description: Role permissions
          type: array
          items:
            type: string
        app_id:
          type: string
          description: Role's app id
        description:
          type: string
          description: Role's description
        display_name:
          type: string
          description: Role's display name
      required:
        - role_id
        - role_name
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
    UserAccessToken:
      type: http
      description: >-
        A token returned upon end-user authentication, which provides access to
        resources and data for the user and app for which it was generated
      scheme: bearer
      bearerFormat: JWT
    AdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by a management application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to all resources for the tenant and its apps
    ClientAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token generated by an end-user application using the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken). It provides
        access to resources and data on the tenant level or associated with the
        specific application (but not other apps in the tenant)
    OrgAdminAccessToken:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oidc/token
          scopes: {}
      description: >-
        A token returned upon B2B authentication for a user that has the
        organizationAdmin or organizationCreator role.