openapi: 3.0.3
info:
  title: Sessions
  description: >-
    Manage sessions and refresh access tokens for silent authentication and SSO
    across apps. These sessions apply to any of the authentication methods
    implemented using a backend-to-backend integration ('Backend
    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: []
paths:
  /v1/auth/session/authenticate:
    post:
      operationId: authenticateSession
      summary: Authenticate session
      description: >-
        Authenticates an existing session in order to obtain an access token
        without explicit user interaction. This enables silent authentication
        and single sign-on (SSO).
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSessionTokenRequest'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
        '400':
          content:
            application/json:
              examples:
                sessionNotFound:
                  value:
                    error_code: '400'
                    message: Session not found
                  description: Session not found
                userNotFound:
                  value:
                    error_code: '400'
                    message: User not found
                  description: User not found
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/token/refresh:
    post:
      operationId: refreshBackendAuthToken
      summary: Refresh access token
      description: >-
        Exchange the refresh token returned upon successful authentication for a
        new access token. <br><br>**Required permissions**: `apps:execute`,
        `[appId]:execute`, `auth:execute`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiRefreshTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRefreshTokenResponseDto'
      security:
        - ClientAccessToken: []
  /v1/auth/session/logout:
    post:
      operationId: logout
      summary: Logout session
      description: >-
        Logs out the user by terminating the provided session.
        <br><br>**Required permissions**: `apps:delete`, `[appId]:delete`,
        `sessions:delete`.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiLogoutRequestDto'
      responses:
        '204':
          description: ''
      security:
        - ClientAccessToken: []
  /v1/auth/users/{userId}/sessions:
    get:
      operationId: getUserSessions
      summary: Get user sessions
      description: >-
        Retrieves all active sessions for a specified user. <br><br>**Required
        permissions**: `apps:read`, `[appId]:read`, `sessions:read`.
      parameters:
        - name: userId
          required: true
          in: path
          description: ID of the user to retrieve active sessions for
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiUserSessionResponse'
      security:
        - ClientAccessToken: []
    delete:
      operationId: revokeUserSessions
      summary: Revoke sessions
      description: >-
        Revokes all user sessions. <br><br>**Required permissions**:
        `apps:delete`, `[appId]:delete`, `sessions:delete`.
      parameters:
        - name: userId
          required: true
          in: path
          description: ID of the user to terminate active sessions for
          schema:
            type: string
      responses:
        '204':
          description: Sessions terminated
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiSessionTokenRequest:
      type: object
      properties:
        resource:
          type: string
          description: >-
            Resource URI the authentication request is attempting to access,
            which is reflected in the audience (`aud` claim) of the access
            token. This must be configured as resource for the application.
        claims:
          example:
            id_token:
              roles: null
          description: >-
            Used to request additional claims in the ID token, such as roles,
            permissions, and other user profile data. The structure is per the
            [OIDC
            Standard](https://openid.net/specs/openid-connect-core-1_0-final.html#ClaimsParameter).
            For supported claims and how to request custom claims, see the [ID
            Token
            Reference](https://developer.transmitsecurity.com/openapi/id_token_reference/).
          allOf:
            - $ref: '#/components/schemas/ApiTokenRequestClaims'
        org_id:
          type: string
          description: Organization ID, used for member login in B2B scenarios
        client_attributes:
          description: Client attributes
          allOf:
            - $ref: '#/components/schemas/ClientAttributes'
        session_id:
          type: string
          description: Authentication session ID returned by other backend methods.
      required:
        - session_id
    ApiTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            User access token for accessing endpoints on behalf of the
            authenticated user.
        id_token:
          type: string
          description: ID token that identifies the user.
        refresh_token:
          type: string
          description: Refresh token used to refresh an expired access token.
        token_type:
          type: string
          description: Bearer.
        expires_in:
          type: number
          description: Expiration time of the access token in seconds.
          default: 3600
        session_id:
          type: string
          description: ID of the session in which the authentication occurs.
      required:
        - access_token
        - token_type
        - expires_in
        - session_id
    ApiRefreshTokenRequestDto:
      type: object
      properties:
        refresh_token:
          type: string
          description: Refresh token associated with the access token you want to refresh.
      required:
        - refresh_token
    ApiRefreshTokenResponseDto:
      type: object
      properties:
        access_token:
          type: string
          description: >-
            User access token for accessing endpoints on behalf of the
            authenticated user.
        id_token:
          type: string
          description: ID token that identifies the user.
        refresh_token:
          type: string
          description: Refresh token used to refresh an expired access token.
        token_type:
          type: string
          description: Bearer.
        expires_in:
          type: number
          description: Expiration time of the access token in seconds.
          default: 3600
      required:
        - access_token
        - token_type
        - expires_in
    ApiLogoutRequestDto:
      type: object
      properties:
        session_id:
          type: string
          description: ID of the session to log out.
      required:
        - session_id
    ApiUserSessionResponse:
      type: object
      properties:
        session_id:
          type: string
          description: Session ID
        start_time:
          format: date-time
          type: string
          description: Session creation time
        expiration_time:
          format: date-time
          type: string
          description: Session expiration time
      required:
        - session_id
        - start_time
        - expiration_time
    ApiTokenRequestClaims:
      type: object
      properties:
        id_token:
          type: object
        access_token:
          type: object
    ClientAttributes:
      type: object
      properties:
        user_agent:
          type: string
        ip_address:
          type: string
  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.
