openapi: 3.0.3
info:
  title: Social Login
  description: >-
    Login users using social login providers like Google Sign-In. This
    implements a backend-to-backend integration for authentication. Irrespective
    of the social login provider, the flow includes three steps: initiating a
    login, submitting the received code to Mosaic, and finally completing
    authentication with Mosaic.
  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/social/google/start:
    post:
      operationId: initGoogleLogin
      summary: Start login with Google
      description: >-
        Starts the Google login flow. This call returns an authorization URL to
        redirect the user to.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialInitRequestDto'
      responses:
        '200':
          description: Backend auth initialized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSocialInitResponseDto'
      security:
        - ClientAccessToken: []
  /v1/auth/social/google/authenticate:
    post:
      operationId: authenticateGoogleLogin
      summary: Complete login with Google
      description: >-
        Completes the Google social login flow and authenticates the user in
        Mosaic.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/facebook/start:
    post:
      operationId: initFacebookLogin
      summary: Start login with Facebook
      description: >-
        Starts the Facebook login flow. This call returns an authorization URL
        to redirect the user to.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialInitRequestDto'
      responses:
        '200':
          description: Backend auth initialized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSocialInitResponseDto'
      security:
        - ClientAccessToken: []
  /v1/auth/social/facebook/authenticate:
    post:
      operationId: authenticateFacebookLogin
      summary: Complete login with Facebook
      description: >-
        Completes the Facebook social login flow and authenticates the user in
        Mosaic.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/apple/start:
    post:
      operationId: initAppleLogin
      summary: Start login with Apple
      description: >-
        Starts the Apple login flow. This call returns an authorization URL to
        redirect the user to.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialInitRequestDto'
      responses:
        '200':
          description: Backend auth initialized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSocialInitResponseDto'
      security:
        - ClientAccessToken: []
  /v1/auth/social/apple/authenticate:
    post:
      operationId: authenticateAppleLogin
      summary: Complete login with Apple
      description: >-
        Completes the Apple social login flow and authenticates the user in
        Mosaic.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/tiktok/start:
    post:
      operationId: initTiktokLogin
      summary: Start login with Tiktok
      description: >-
        Starts the Tiktok login flow. This call returns an authorization URL to
        redirect the user to.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialInitRequestDto'
      responses:
        '200':
          description: Backend auth initialized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSocialInitResponseDto'
      security:
        - ClientAccessToken: []
  /v1/auth/social/tiktok/authenticate:
    post:
      operationId: authenticateTiktokLogin
      summary: Complete login with Tiktok
      description: >-
        Completes the Tiktok social login flow and authenticates the user in
        Mosaic.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialTokenRequestDto'
      responses:
        '200':
          description: Returns user tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTokenResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/google/verify:
    post:
      operationId: verifyGoogleToken
      summary: Submit code from Google
      description: >-
        Submits the authorization code returned by Google to exchange for user
        identity information
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialVerifyRequest'
      responses:
        '200':
          description: Returns user claims and transaction ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGoogleVerifyResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/facebook/verify:
    post:
      operationId: verifyFacebookToken
      summary: Submit code from Facebook
      description: >-
        Submits the authorization code returned by Facebook to exchange for user
        identity information
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialVerifyRequest'
      responses:
        '200':
          description: Returns user claims and transaction ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFacebookVerifyResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/apple/verify:
    post:
      operationId: verifyAppleToken
      summary: Submit code from Apple
      description: >-
        Submits the authorization code returned by Apple to exchange for user
        identity information
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialVerifyRequest'
      responses:
        '200':
          description: Returns user claims and transaction ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAppleVerifyResponse'
      security:
        - ClientAccessToken: []
  /v1/auth/social/tiktok/verify:
    post:
      operationId: verifyTiktokToken
      summary: Submit code from TikTok
      description: >-
        Submits the authorization code returned by TikTok to exchange for user
        identity information
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiSocialVerifyRequest'
      responses:
        '200':
          description: Returns user claims and transaction ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiTiktokVerifyResponse'
      security:
        - ClientAccessToken: []
components:
  schemas:
    ApiSocialInitRequestDto:
      type: object
      properties:
        redirect_uri:
          type: string
          example: https://www.example.com/login
          description: >-
            The URI the identity provider will redirect the user to after
            authentication. Must match one of the pre-configured redirect URIs
            in the application's social login settings. This URI will receive
            the authorization code that can be exchanged for user information.
        state:
          type: string
          description: >-
            An opaque string that is used to maintain state between the request
            and the callback. It will be added to the redirect URI as a query
            parameter, which should be validated by your server to protect
            against cross-site request forgery (CSRF) attacks
      required:
        - redirect_uri
    ApiSocialInitResponseDto:
      type: object
      properties:
        authorization_url:
          type: string
          example: https://www.provider.com/auth
          description: >-
            The social provider's authorization URL that the client should
            redirect the user to in order to authenticate with this social
            provider.
      required:
        - authorization_url
    ApiSocialTokenRequestDto:
      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: >-
            Used to associate the authentication with an existing session (such
            as for MFA). If unspecified, a new session is created and the
            session ID is returned.
        transaction_id:
          type: string
          description: >-
            The transaction identifier that was previously returned by the
            verification endpoint. This ID is required to associate this
            authentication request with the verified token information stored
            during the verification step.
        user_id:
          type: string
          description: An identifier of the user for whom the token is being requested
      required:
        - transaction_id
        - user_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
    ApiSocialVerifyRequest:
      type: object
      properties:
        code:
          type: string
          description: The code received from the social login provider
        state:
          type: string
          description: >-
            An opaque string that is used to maintain state between the request
            and the callback. It will be added to the redirect URI as a query
            parameter, which should be validated by your server to protect
            against cross-site request forgery (CSRF) attacks
      required:
        - code
        - state
    ApiGoogleVerifyResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: >-
            A unique identifier generated during token verification that links
            this verification process to subsequent authentication requests.
            This transaction_id must be included in the authentication request
            to complete the social login flow.
        claims:
          type: object
          description: >-
            An object containing user identity information extracted from the
            verified social provider token. This includes standard profile
            details such as name, email, and unique identifiers from the social
            provider.
      required:
        - transaction_id
        - claims
    ApiFacebookVerifyResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: >-
            A unique identifier generated during token verification that links
            this verification process to subsequent authentication requests.
            This transaction_id must be included in the authentication request
            to complete the social login flow.
        claims:
          type: object
          description: >-
            An object containing user identity information extracted from the
            verified social provider token. This includes standard profile
            details such as name, email, and unique identifiers from the social
            provider.
      required:
        - transaction_id
        - claims
    ApiAppleVerifyResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: >-
            A unique identifier generated during token verification that links
            this verification process to subsequent authentication requests.
            This transaction_id must be included in the authentication request
            to complete the social login flow.
        claims:
          type: object
          description: >-
            An object containing user identity information extracted from the
            verified social provider token. This includes standard profile
            details such as name, email, and unique identifiers from the social
            provider.
      required:
        - transaction_id
        - claims
    ApiTiktokVerifyResponse:
      type: object
      properties:
        transaction_id:
          type: string
          description: >-
            A unique identifier generated during token verification that links
            this verification process to subsequent authentication requests.
            This transaction_id must be included in the authentication request
            to complete the social login flow.
        claims:
          type: object
          description: >-
            An object containing user identity information extracted from the
            verified social provider token. This includes standard profile
            details such as name, email, and unique identifiers from the social
            provider.
      required:
        - transaction_id
        - claims
    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.
