openapi: 3.0.3
info:
  title: One-Time Login Applications Organizations API
  description: Login users using one-time login methods like magic links or OTPs. This implements a backend-to-backend integration for authentication.
  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: []
tags:
- name: Organizations
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: []
      tags:
      - Organizations
    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: []
      tags:
      - Organizations
  /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: []
      tags:
      - Organizations
    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: []
      tags:
      - Organizations
    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: []
      tags:
      - Organizations
  /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: []
      tags:
      - Organizations
  /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: []
      tags:
      - Organizations
    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: []
      tags:
      - Organizations
  /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: []
      tags:
      - Organizations
  /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: []
      tags:
      - Organizations
components:
  schemas:
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
      - message
      - error_code
    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
    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
    LogoUploadDto:
      type: object
      properties:
        logo:
          type: string
          format: binary
      required:
      - logo
    BadRequestHttpError:
      type: object
      properties:
        message:
          example: Bad request
          type: array
          items:
            type: string
        error_code:
          type: number
          example: 400
      required:
      - message
      - error_code
    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
    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
  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.