openapi: 3.0.3
info:
  title: Single Sign-On
  description: >-
    Login users using an external SAML identity provider (IDP). B2B apps can use
    this to allow their business customers or partners to provide SSO login for
    their members (see
    [Organizations](/openapi/user/organizations.openapi.json)).
  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/auth/sso/saml/start:
    get:
      operationId: startSamlLogin
      summary: Start SAML SSO
      deprecated: true
      description: >-
        Initiates an SSO login flow with a SAML identity provider (IDP). This
        results in a POST redirect to the SAML IDP configured for the
        organization, which is determined based on the domain of the user's
        email address. Once the SAML IDP authenticates the user, it will
        redirect back to the app with the SAML response so the app can complete
        the SSO flow. <br><br>**Note:** <ul> <li> If the user isn't a
        [member](/openapi/user/members.openapi.json) of an organization
        configured for SAML SSO, an error is returned.</li><li> If [public
        sign-ups](/guides/user/manage_apps/#advanced-settings) are enabled for
        the app, new users will be added to the app upon login.</li></ul>
      parameters:
        - name: client_id
          required: true
          in: query
          description: Client ID
          schema:
            type: string
        - name: email
          required: true
          in: query
          description: User's email address
          schema:
            type: string
        - name: org_id
          required: false
          in: query
          description: Organization ID, used for member login in B2B scenarios
          schema:
            type: string
      responses:
        '200':
          description: POST redirect to SAML IDP with a SAML request
  /v1/auth/sso/saml/complete:
    post:
      operationId: completeSamlLogin
      summary: Complete SAML SSO
      deprecated: true
      description: >-
        Completes the SSO login using the SAML response received directly from
        the SAML IDP (via your ACS URL). If the user is authenticated and the
        SAML response is valid, Transmit will redirect to your redirect URI with
        a code that can be exchanged for a user token. If not, this API returns
        an error. <br><br>This should be called from the backend, using a
        [client access token](/openapi/token.openapi/other/getaccesstoken).
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCompleteSamlInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedirectUriResponse'
  /v1/auth/sso/start:
    get:
      operationId: startSsoLogin
      summary: Start SSO
      description: >-
        Initiates an SSO login flow with an external identity provider (IDP).
        This results in a POST redirect to the IDP configured for the
        organization, which is determined based on the domain of the user's
        email address. Once the IDP authenticates the user, it will redirect
        back to the app with the authentication response so the app can complete
        the SSO flow. <br><br>**Note:** <ul> <li> If the user isn't a
        [member](/openapi/user/members.openapi.json) of an organization
        configured for SSO, an error is returned.</li><li> If [public
        sign-ups](/guides/user/manage_apps/#advanced-settings) are enabled for
        the app, new users will be added to the app upon login.</li></ul>
      parameters:
        - name: client_id
          required: true
          in: query
          description: Client ID
          schema:
            type: string
        - name: email
          required: true
          in: query
          description: User's email address
          schema:
            type: string
        - name: redirect_uri
          required: true
          in: query
          description: the client pre-listed redirect uri
          schema:
            type: string
        - name: org_id
          required: false
          in: query
          description: Organization ID, used for member login in B2B scenarios
          schema:
            type: string
      responses:
        '200':
          description: POST redirect to IDP with a SSO request
components:
  schemas:
    ApiCompleteSamlInput:
      type: object
      properties:
        SAMLResponse:
          type: string
          description: SAML response from the SAML IDP
        RelayState:
          type: string
          description: >-
            `RelayState` returned with the SAML response (only for SP-initiated
            flows). It's an opaque identifier used to maintain the state of the
            user session.
        organization_id:
          type: string
          description: Organization ID. This can be part of your app's ACS URL path.
        redirect_uri:
          type: string
          description: >-
            URI to redirect to upon completing the SSO login. This is the server
            GET endpoint used to call the [token
            endpoint](/openapi/user/oidc.openapi/other/oidctoken), and should
            accept `code` as a query parameter. This URI must also be configured
            as an allowed redirect URI for this client.
      required:
        - SAMLResponse
        - organization_id
        - redirect_uri
    RedirectUriResponse:
      type: object
      properties:
        result:
          type: string
          readOnly: true
          description: >-
            URI used to complete the flow. Sending a GET request to this URI
            will redirect the browser to your redirect URI with a code to
            exchange for user tokens.
      required:
        - result
  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.
