openapi: 3.0.3
info:
  title: Service Providers
  description: >-
    Manage third-party service providers that can use Transmit Security as an
    Identity Provider
  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/serviceprovider/saml2:
    post:
      operationId: createServiceProvider
      summary: Create SAML provider
      description: >-
        Create a SAML access-based service provider in a specific tenant.
        <br><br>**Required permissions**: `service-providers:create`,
        `apps:create`, `[appId]:create`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateServiceProviderInput'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                title: ApiCreatedResponse-createServiceProvider
                type: object
                required:
                  - result
                description: Service provider successfully created in tenant
                properties:
                  result:
                    $ref: '#/components/schemas/ApiServiceProvider'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
      security:
        - ClientAccessToken: []
    get:
      operationId: getServiceProvider
      summary: Get SAML providers
      description: >-
        Get all SAML access-based service providers in a specific tenant.
        <br><br>**Required permissions**: `service-providers:list`,
        `service-providers:read`, `apps:list`, `[appId]:list`, `apps:read`,
        `[appId]:read`.
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-getServiceProvider
                type: object
                required:
                  - result
                description: ''
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiServiceProvider'
      security:
        - ClientAccessToken: []
  /v1/serviceprovider/saml2/{serviceProviderId}:
    put:
      operationId: updateServiceProvider
      summary: Update SAML provider
      description: >-
        Update the specified SAML service provider. <br><br>**Required
        permissions**: `service-providers:edit`, `apps:edit`, `[appId]:edit`.
      parameters:
        - name: serviceProviderId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateServiceProviderInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: ApiOkResponse-updateServiceProvider
                type: object
                required:
                  - result
                description: Service provider successfully updated
                properties:
                  result:
                    $ref: '#/components/schemas/ApiServiceProvider'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderNotFoundHttpError'
      security:
        - ClientAccessToken: []
    delete:
      operationId: deleteServiceProvider
      summary: Delete SAML provider
      description: >-
        Delete the specified SAML service provider. <br><br>**Required
        permissions**: `service-providers:delete`, `apps:delete`,
        `[appId]:delete`.
      parameters:
        - name: serviceProviderId
          required: true
          in: path
          schema:
            type: string
      responses:
        '204':
          description: ''
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderNotFoundHttpError'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderInUseHttpError'
      security:
        - ClientAccessToken: []
  /v1/serviceprovider/saml2/sso/{serviceProviderId}:
    get:
      operationId: createSamlResponse
      summary: SAML SSO
      description: >-
        Exchanges a user access token for a SAML response, used to perform an
        SSO login into a SAML service provider. The user access token, retrieved
        via a successful login with Transmit, is used to authorize this request.
      parameters:
        - name: serviceProviderId
          required: true
          in: path
          schema:
            type: string
        - name: SAMLRequest
          required: false
          in: query
          description: SAMLRequest
          schema:
            type: string
        - name: RelayState
          required: false
          in: query
          description: RelayState
          schema:
            type: string
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                title: ApiCreatedResponse-createSamlResponse
                type: object
                required:
                  - result
                description: Saml successfully created.
                properties:
                  result:
                    $ref: '#/components/schemas/SamlResponseDTO'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestHttpError'
      security:
        - UserAccessToken: []
components:
  schemas:
    ApiCreateServiceProviderInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the service provider
          example: My service provider
        description:
          type: string
          description: Short description of the service provider
        assertion_consumer_service_URL:
          type: string
          description: Assertion consumer service URL, which receives the SAML response
          example: https://example.com/sso/saml
        entity_id:
          type: string
          description: Entity ID (Also referred to as Audience)
          example: https://example.com
        name_qualifier:
          type: string
          description: Name Qualifier
          example: https://yourdomain.example.com/
      required:
        - name
        - assertion_consumer_service_URL
        - entity_id
    BadRequestHttpError:
      type: object
      properties:
        message:
          example: Bad request
          type: array
          items:
            type: string
        error_code:
          type: number
          example: 400
      required:
        - message
        - error_code
    ApiServiceProvider:
      type: object
      properties:
        service_provider_id:
          type: string
          description: Service provider ID autogenerated upon creation
        tenant_id:
          type: string
          description: Transmit tenant ID
        name:
          type: string
          description: Service provider friendly name
        description:
          type: string
          description: Service provider description
        assertion_consumer_service_URL:
          type: string
          description: Assertion consumer service URL, which receives the SAML response
        entity_id:
          type: string
          description: Entity ID (Also referred to as Audience)
        name_qualifier:
          type: string
          description: Name Qualifier
        saml_url:
          type: string
          description: Transmit's SAML SSO endpoint that receives authentication requests
        issuer:
          type: string
          description: Identifies Transmit as the issuer of the SAML response
        pub_cert:
          type: string
          description: >-
            X.509 certificate containing Transmit's public key, used to validate
            the signed SAML assertion
      required:
        - service_provider_id
        - tenant_id
        - name
        - assertion_consumer_service_URL
        - entity_id
    ApiUpdateServiceProviderInput:
      type: object
      properties:
        name:
          type: string
          description: Name of the service provider
          example: My service provider
        description:
          type: string
          description: Short description of the service provider
        assertion_consumer_service_URL:
          type: string
          description: Assertion consumer service URL, which receives the SAML response
          example: https://example.com/sso/saml
        entity_id:
          type: string
          description: Entity ID (Also referred to as Audience)
          example: https://example.com
        name_qualifier:
          type: string
          description: Name Qualifier
          example: https://yourdomain.example.com/
    ServiceProviderNotFoundHttpError:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Service provider does not exist in tenant
        error_code:
          type: number
          readOnly: true
          example: 404
      required:
        - message
        - error_code
    ServiceProviderInUseHttpError:
      type: object
      properties:
        message:
          type: string
          readOnly: true
          example: Service provider in use
        error_code:
          type: number
          readOnly: true
          example: 409
      required:
        - message
        - error_code
    SamlResponseDTO:
      type: object
      properties:
        SsoUrl:
          type: string
        SAMLResponse:
          type: string
        RelayState:
          type: string
      required:
        - SsoUrl
        - SAMLResponse
        - RelayState
  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.
