openapi: 3.0.3
info:
  title: Members
  description: >-
    In business-to-business (B2B) use cases, members are the users of your
    business customers and partners (managed as organizations of the tenant).
  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/applications/{app_id}/organizations/{organization_id}/members/{member_id}/roles:
    post:
      operationId: setRoles
      summary: Set member's roles
      description: >-
        Update the roles of a member of the organization to control their access
        to an application. This will replace all the member's roles, if they
        exist. The roles must first be created for the application and added to
        a role group for the application, and the role group must be added to
        the organization. <br><br>**Required permissions**:
        `organizations:edit`, `orgs:edit`.
      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
        - name: member_id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSetRolesToMemberInput'
      responses:
        '204':
          description: ''
      security:
        - AdminAccessToken: []
  /v1/members/{member_id}/organizations:
    get:
      operationId: getMemberOrgsById
      summary: Get member's roles
      description: Get member's roles in app per organization
      parameters:
        - name: member_id
          required: true
          in: path
          description: ID of the member
          schema:
            type: string
        - name: organization_id
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getMemberOrgsById
                type: object
                required:
                  - result
                description: >-
                  The member roles in the app per organization. Each key is the
                  organization ID and the value is the list of roles assigned to
                  the member in that organization.
                properties:
                  result:
                    $ref: '#/components/schemas/ApiMemberOrgAssignments'
      security:
        - ClientAccessToken: []
  /v1/organizations/{organization_id}/members/{user_id}:
    get:
      operationId: getMemberByIdInApp
      summary: Get member by ID
      description: >-
        Allows an end-user app to search for a member of an organization by
        their user ID. This should be called from the backend, using a client
        access token (generated by an end-user app). <br><br>**Required
        permissions**: `apps:read`, `[appId]:read`, `users:read`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getMemberByIdInApp
                type: object
                required:
                  - result
                description: ''
                properties:
                  result:
                    $ref: '#/components/schemas/ApiMember'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundHttpError'
      security:
        - OrgAdminAccessToken: []
        - ClientAccessToken: []
    put:
      operationId: updateMember
      summary: Update member
      description: >-
        Update the membership details of the specified user. This should be
        called from the backend, using an admin access token (generated by a
        management app). <br><br>**Required permissions**: `apps:edit`,
        `[appId]:edit`, `users:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiOrganizationInformationInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleUserIdResponse'
      security:
        - OrgAdminAccessToken: []
        - ClientAccessToken: []
    patch:
      operationId: updateOrganizationMember
      summary: Update member
      description: >-
        Update the member details of the specified user. This should be called
        from the backend, using an admin access token (generated by a management
        app). <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`,
        `users:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
        - name: user_id
          required: true
          in: path
          description: ID of the user
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateMemberInput'
      responses:
        '200':
          description: ''
      security:
        - OrgAdminAccessToken: []
        - ClientAccessToken: []
    delete:
      operationId: removeMemberFromApplication
      summary: Remove member from application
      description: >-
        Remove a member from an application. Once removed, the member will no
        longer be associated with the application. This should be called from
        the backend, using an app access token. <br><br>**Required
        permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
        - name: user_id
          required: true
          in: path
          description: ID of the user to remove
          schema:
            type: string
      responses:
        '204':
          description: ''
      security:
        - OrgAdminAccessToken: []
        - ClientAccessToken: []
  /v1/organizations/{organization_id}/members:
    post:
      operationId: createOrAssignMember
      summary: Create or assign member
      description: >-
        Create a new user in Transmit or assign an existing one as a member to
        the organization. A user must be created with at least one of the
        following: email, phone number, or username (used for password
        authentication). However, an email address is required to federate login
        using a SAML identity provider. The response contains a user ID that can
        be used to identify the user/member whenever needed. <br><br>**Required
        permissions**: `apps:create`, `[appId]:create`, `users:create`.
      parameters:
        - 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/ApiCreateOrUpdateMemberInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleUserIdResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentifierIsTakenHttpError'
      security:
        - OrgAdminAccessToken: []
        - ClientAccessToken: []
    get:
      operationId: getAllApplicationMembers
      summary: Get all application's members
      description: >-
        Allows an app to get all members of an organization. This should be
        called from the backend, using a client access token (generated by an
        end-user app). <br><br>**Required permissions**: `apps:read`,
        `[appId]:read`, `users:read`, `apps:list`, `[appId]:list`, `users:list`.
      parameters:
        - name: organization_id
          required: true
          in: path
          description: ID of the organization
          schema:
            type: string
        - name: search
          required: false
          in: query
          description: >-
            Search expression based on the [SCIM
            protocol](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2).
            For syntax and searchable fields, see [Search query
            syntax](/openapi/scim_search_syntax/)
          schema:
            type: string
        - name: role_values
          required: false
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetAllMembers'
      security:
        - OrgAdminAccessToken: []
        - ClientAccessToken: []
components:
  schemas:
    ApiSetRolesToMemberInput:
      type: object
      properties:
        role_ids:
          description: Ids of the roles
          example:
            - role1
            - role2
          type: array
          items:
            type: string
      required:
        - role_ids
    ApiMemberOrgAssignments:
      type: object
      properties: {}
    BadRequestHttpError:
      type: object
      properties:
        message:
          example: Bad request
          type: array
          items:
            type: string
        error_code:
          type: number
          example: 400
      required:
        - message
        - error_code
    NotFoundHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
          example: 404
      required:
        - message
        - error_code
    ApiMember:
      type: object
      properties:
        email:
          description: Primary email address, used as user identifier
          allOf:
            - $ref: '#/components/schemas/ApiUserEmail'
        secondary_emails:
          type: array
          items:
            $ref: '#/components/schemas/ApiUserEmail'
        phone_number:
          description: Primary phone number, used as user identifier
          allOf:
            - $ref: '#/components/schemas/ApiUserPhone'
        secondary_phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/ApiUserPhone'
        username:
          type: string
          description: >-
            Username used to identify the user for password login (unless a
            primary email will be used instead). Defined only if a password was
            set for the user.
        user_id:
          type: string
          description: User ID autogenerated upon user creation
        birthday:
          format: date-time
          type: string
          description: Birthday as YYYY-MM-DD
        address:
          description: User's address
          allOf:
            - $ref: '#/components/schemas/ApiAddress'
        name:
          description: Full name
          allOf:
            - $ref: '#/components/schemas/ApiUserName'
        status:
          $ref: '#/components/schemas/Status'
        status_changed_at:
          format: date-time
          type: string
          description: Date status was last updated
        created_at:
          type: number
          description: Date user was created in the tenant
        updated_at:
          type: number
          description: Date user was last updated
        identity_providers:
          deprecated: true
          type: array
          items:
            $ref: '#/components/schemas/ApiUserIdentityProvider'
        identities:
          type: array
          items:
            $ref: '#/components/schemas/ApiUserIdentity'
        last_auth:
          format: date-time
          type: string
          description: Date user last authenticated
        external_account_id:
          type: string
          description: User identifier in an app, set by the app
        app_name:
          type: string
          description: Name of the app the user is associated with
        custom_app_data:
          type: object
          description: Custom data object for app-related user info
        groupIds:
          description: List of group IDs the user is assigned to
          type: array
          items:
            type: string
        picture:
          type: string
          description: The picture of user, specified as a URL
        language:
          type: string
          description: >-
            The language of the user, as provided by the browser using the
            [Accept-Language](https://www.rfc-editor.org/rfc/rfc7231#section-5.3.5)
            header field
        custom_data:
          type: object
          description: Custom data object for tenant user info
        external_user_id:
          type: string
          description: A unique identifier in a tenant
        password_information:
          description: The information of the user's password
          allOf:
            - $ref: '#/components/schemas/ApiPasswordInformation'
        organization_information:
          description: The organizations the member is part of
          allOf:
            - $ref: '#/components/schemas/ApiMemberOrganizationInformation'
        roles:
          description: The roles the member has in the organization
          type: array
          items:
            $ref: '#/components/schemas/ApiRoleData'
      required:
        - user_id
        - status
        - created_at
        - updated_at
        - organization_information
    ApiOrganizationInformationInput:
      type: object
      properties:
        enabled:
          type: boolean
          description: Indicates if the user's membership is currently enabled
          default: true
        department:
          type: string
          description: The department of the user within the organization
        title:
          type: string
          description: The title of the user within the organization
        manager:
          type: string
          description: The manager of the user within the organization
    SingleUserIdResponse:
      type: object
      properties:
        result:
          readOnly: true
          description: User ID autogenerated upon user creation
          allOf:
            - $ref: '#/components/schemas/UserIdParams'
      required:
        - result
    ApiUpdateMemberInput:
      type: object
      properties:
        name:
          description: The member's name information
          allOf:
            - $ref: '#/components/schemas/ApiUserNameInput'
        email:
          type: string
          description: Primary email address of the user
        phone_number:
          type: string
          description: Primary phone number of the user, specified in E.164 format
        language:
          type: string
          description: >-
            The language of the user, as provided by the browser using the
            [Accept-Language](https://www.rfc-editor.org/rfc/rfc7231#section-5.3.5)
            header field
    ApiGetAllMembers:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/ApiMember'
      required:
        - result
    ApiCreateOrUpdateMemberInput:
      type: object
      properties:
        email:
          type: string
          description: Primary email address of the user
        phone_number:
          type: string
          description: Primary phone number of the user, specified in E.164 format
        username:
          type: string
          description: Username used to identify the user
        secondary_emails:
          description: Secondary email addresses to add to user's current emails
          type: array
          items:
            type: string
        secondary_phone_numbers:
          description: >-
            Secondary phone numbers to add to user's phone numbers, each
            specified in E.164 format
          type: array
          items:
            type: string
        birthday:
          format: date-time
          type: string
          description: User's birthday
        address:
          description: User's address
          allOf:
            - $ref: '#/components/schemas/ApiCreateOrUpdateAddressInput'
        name:
          description: Object describing user's full name
          allOf:
            - $ref: '#/components/schemas/ApiUserNameInput'
        external_account_id:
          type: string
          description: User identifier in an app, set by the app
        custom_app_data:
          type: object
          description: Custom data object for app-related user info
        picture:
          type: string
          description: The picture of user, specified as a URL
        language:
          type: string
          description: >-
            The language of the user, as provided by the browser using the
            [Accept-Language](https://www.rfc-editor.org/rfc/rfc7231#section-5.3.5)
            header field
        custom_data:
          type: object
          description: Custom data object for tenant user info
        external_user_id:
          type: string
          description: A unique identifier in a tenant
        credentials:
          description: >-
            The password of the user, who is identified by either a username or
            primary email.
          allOf:
            - $ref: '#/components/schemas/ApiUserPasswordInput'
        delegated_access:
          description: >-
            If this user is a dependent, this defines the permissions that the
            primary user will have to act on behalf of the dependent user.
          allOf:
            - $ref: '#/components/schemas/DelegatedAccessInput'
        organization_information:
          description: Membership details
          allOf:
            - $ref: '#/components/schemas/ApiOrganizationInformationInput'
        role_ids:
          description: role ids to assign the member to.
          type: array
          items:
            type: string
        send_invite:
          type: boolean
          description: >-
            If true, sends the member an invitation email for each app the
            member is assigned to. The email contains an invite link that
            redirects to the app's login experience. Once authenticated, the
            member will be assigned to the app, their email address will be
            verified, and their status will be updated to active. The invitation
            is valid for 48 hours.
      required:
        - role_ids
    IdentifierIsTakenHttpError:
      type: object
      properties:
        message:
          type: string
        error_code:
          type: number
      required:
        - message
        - error_code
    Status:
      type: string
      enum:
        - Active
        - Disabled
        - Pending
    ApiUserEmail:
      type: object
      properties:
        value:
          type: string
          description: Email address
        email_verified:
          type: boolean
          description: >-
            Indicates if email was verified (via magic link, social login, or
            email verification flows)
        verified_at:
          format: date-time
          type: string
          description: Last verification date of the email
      required:
        - value
    ApiUserPhone:
      type: object
      properties:
        value:
          type: string
          description: Phone number
        phone_number_verified:
          type: boolean
          description: >-
            Indicates if phone number was verified (via SMS OTP or verification
            flow)
        verified_at:
          format: date-time
          type: string
          description: Last verification date of the phone number
      required:
        - value
    ApiUserIdentityProvider:
      type: object
      properties:
        source:
          type: string
          description: Type of identity provider
          enum:
            - UserID
            - BindID
            - Google
            - Apple
            - Facebook
            - Line
            - Tiktok
            - Transmit Identity
            - Transmit Security
            - BindIDApi
            - Email OTP
            - SMS OTP
            - Direct OTP
            - Email Magic Link
            - Password
            - Orchestrated
            - SAML
            - SSO OIDC
            - Mobile Biometrics
            - totp
            - face
        identifier:
          type: string
          description: Identifier of the user in the provider's system
        email:
          type: string
          description: Email used by the user to authenticate to this provider
        first_auth_date:
          format: date-time
          type: string
          description: Date user first authenticated to this provider
        last_auth_date:
          format: date-time
          type: string
          description: Date user last authenticated to this provider
      required:
        - source
        - identifier
        - email
        - first_auth_date
        - last_auth_date
    ApiUserIdentity:
      type: object
      properties:
        provider_name:
          type: string
          description: Name of identity provider
        provider_type:
          type: string
          description: >-
            Indicates whether the identity provider is Transmit (Native) or a
            social login provider (OAuth2)
          enum:
            - OAuth2
            - Native
            - External
        auth_type:
          type: string
          enum:
            - webauthn
            - email_otp
            - sms_otp
            - direct_otp
            - email_magic_link
            - password
            - oauth2
            - saml
            - transmit
            - totp
          description: Type of authentication method that was used
        identifier:
          type: string
          description: Identifier of the user in the provider's system
        user_alias:
          description: Alias used by the user to authenticate to this provider
          allOf:
            - $ref: '#/components/schemas/ApiUserIdentityAlias'
        first_auth_date:
          format: date-time
          type: string
          description: Date user first authenticated to this provider
        last_auth_date:
          format: date-time
          type: string
          description: Date user last authenticated to this provider
      required:
        - provider_name
        - provider_type
        - auth_type
        - identifier
        - first_auth_date
        - last_auth_date
    ApiRoleData:
      type: object
      properties:
        role_id:
          type: string
          description: Role ID
        role_name:
          type: string
          description: Role name
        display_name:
          type: string
          description: Role display name
      required:
        - role_id
        - role_name
    ApiAddress:
      type: object
      properties:
        country:
          type: string
          description: Country
          maximum: 30
        state:
          type: string
          description: State
          maximum: 30
        city:
          type: string
          description: City
          maximum: 30
        street_address:
          type: string
          description: Street address
          maximum: 150
        postal_code:
          type: string
          description: Postal code
          maximum: 30
        type:
          $ref: '#/components/schemas/AddressType'
        updated_at:
          type: number
          description: Date user's address was last updated
    ApiUserName:
      type: object
      properties:
        title:
          type: string
          description: Title
          maximum: 30
        first_name:
          type: string
          description: User's first name
          maximum: 30
        last_name:
          type: string
          description: User's last name
          maximum: 30
        middle_name:
          type: string
          description: User's middle name
          maximum: 30
    ApiPasswordInformation:
      type: object
      properties:
        expired:
          type: boolean
          description: Whether the password is currently expired
        temporary:
          type: boolean
          description: Whether the password must be reset after first use
        updated_at:
          type: number
          description: >-
            The date the password was last updated, as unix epoch in
            milliseconds
        expires_in:
          format: date-time
          type: string
          description: The date the password will be expired
      required:
        - expired
        - temporary
        - updated_at
    ApiMemberOrganizationInformation:
      type: object
      properties:
        organization_id:
          type: string
          description: The organizationId
        name:
          type: string
          description: The organization name
        added_by:
          type: string
          description: The ID of who added this user
        department:
          type: string
          description: The department of the user within the organization
        title:
          type: string
          description: The title of the user within the organization
        manager:
          type: string
          description: The manager of the user within the organization
        enabled:
          type: boolean
          description: Indicates if the user's membership is currently enabled
        added_at:
          type: number
          description: The time when the member was added to the organization
        updated_at:
          type: number
          description: The time when the member was last updated in the organization
        logo_url:
          type: string
          description: The URL of the organization's logo
        alias:
          type: string
          description: The organization alias name
        assigned_apps:
          description: >-
            The app id and roles that the user is assigned to on the
            organization
          type: array
          items:
            $ref: '#/components/schemas/ApiOrganizationAssignedAppOutput'
      required:
        - organization_id
        - name
        - added_by
    UserIdParams:
      type: object
      properties:
        user_id:
          type: string
          description: ID of the user
      required:
        - user_id
    ApiUserNameInput:
      type: object
      properties:
        title:
          type: string
          description: Title
        first_name:
          type: string
          description: User's first name
        last_name:
          type: string
          description: User's last name
        middle_name:
          type: string
          description: User's middle name
    ApiCreateOrUpdateAddressInput:
      type: object
      properties:
        country:
          type: string
          description: Country
        state:
          type: string
          description: State
        city:
          type: string
          description: City
        street_address:
          type: string
          description: Street address
        postal_code:
          type: string
          description: Postal code
        type:
          $ref: '#/components/schemas/AddressType'
    ApiUserPasswordInput:
      type: object
      properties:
        password:
          type: string
          description: The user's new password
        force_replace:
          type: boolean
          description: >-
            When true the password is temporary and the user will be required to
            replace it upon successful login
          default: true
      required:
        - password
    DelegatedAccessInput:
      type: object
      properties:
        actor_id:
          type: string
          description: >-
            The ID of the primary user that has permissions to act on behalf of
            this user
        permissions:
          description: >-
            Names of permissions that are granted to the primary user on behalf
            of the dependent
          type: array
          items:
            type: string
      required:
        - actor_id
        - permissions
    AddressType:
      type: string
      enum:
        - Home
        - Work
        - Other
    ApiOrganizationAssignedAppOutput:
      type: object
      properties:
        app_id:
          type: string
          description: The app Id
        roles:
          description: The roles the user has in the organization and app
          type: array
          items:
            $ref: '#/components/schemas/ApiRoleData'
      required:
        - app_id
    ApiUserIdentityAlias:
      type: object
      properties:
        type:
          type: string
          description: Alias type, which varies based on authentication method
          enum:
            - username
            - email
            - phone_number
            - unspecified
        value:
          type: string
          description: Alias value
      required:
        - type
        - value
  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.
