{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://developer.transmitsecurity.com/schemas/backend-authentication",
  "title": "Transmit Security One-Time Login Schemas",
  "description": "JSON Schema definitions for Transmit Security backend-authentication API",
  "definitions": {
    "ApiMagicLinkInitWithIdentifierRequestDto": {
      "type": "object",
      "properties": {
        "device_id": {
          "type": "string",
          "description": "Identifier of the device from which the authentication request originates",
          "maxLength": 80
        },
        "redirect_uri": {
          "type": "string",
          "example": "https://www.example.com/verify",
          "description": "URI that receives a code when the user clicks the email link. This is your server GET endpoint used to complete the authentication, and should accept 'code' as a query parameter. This URI must be configured as an allowed redirect URI for your Transmit client."
        },
        "email_content": {
          "description": "Texts, logo and color to render email template with",
          "allOf": [
            {
              "$ref": "#/components/schemas/EmailContentAttributes"
            }
          ]
        },
        "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"
        },
        "email_expiration": {
          "type": "number",
          "description": "invitation link expiration in minutes"
        },
        "channel": {
          "type": "string",
          "enum": [
            "email",
            "direct"
          ],
          "description": "Channel to use to send the magic link"
        },
        "client_attributes": {
          "description": "Client attributes",
          "allOf": [
            {
              "$ref": "#/components/schemas/ClientAttributes"
            }
          ]
        },
        "generate_request_id": {
          "type": "boolean",
          "description": "The request ID can serve as an additional security identifier for authentication requests. When set to 'false' (by default), the request ID isn't returned. When set to 'true',  Mosaic generates a unique request ID that must be included in the subsequent Authenticate OTP request along with other required parameters.",
          "default": false
        },
        "identifier": {
          "type": "string",
          "example": "name@example.com",
          "description": "Identifier value (email, phone number, user ID, or custom identifier)"
        },
        "identifier_type": {
          "type": "string",
          "example": "email",
          "description": "Type of identifier (email, phone_number, user_id, username, or custom identifier type)"
        }
      },
      "required": [
        "redirect_uri",
        "identifier",
        "identifier_type"
      ]
    },
    "ApiMagicLinkInitWithEmailRequestDto": {
      "type": "object",
      "properties": {
        "device_id": {
          "type": "string",
          "description": "Identifier of the device from which the authentication request originates",
          "maxLength": 80
        },
        "redirect_uri": {
          "type": "string",
          "example": "https://www.example.com/verify",
          "description": "URI that receives a code when the user clicks the email link. This is your server GET endpoint used to complete the authentication, and should accept 'code' as a query parameter. This URI must be configured as an allowed redirect URI for your Transmit client."
        },
        "email_content": {
          "description": "Texts, logo and color to render email template with",
          "allOf": [
            {
              "$ref": "#/components/schemas/EmailContentAttributes"
            }
          ]
        },
        "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"
        },
        "email_expiration": {
          "type": "number",
          "description": "invitation link expiration in minutes"
        },
        "channel": {
          "type": "string",
          "enum": [
            "email",
            "direct"
          ],
          "description": "Channel to use to send the magic link"
        },
        "client_attributes": {
          "description": "Client attributes",
          "allOf": [
            {
              "$ref": "#/components/schemas/ClientAttributes"
            }
          ]
        },
        "generate_request_id": {
          "type": "boolean",
          "description": "The request ID can serve as an additional security identifier for authentication requests. When set to 'false' (by default), the request ID isn't returned. When set to 'true',  Mosaic generates a unique request ID that must be included in the subsequent Authenticate OTP request along with other required parameters.",
          "default": false
        },
        "email": {
          "type": "string",
          "example": "name@example.com",
          "description": "Email of the user (deprecated, use identifier and identifier_type instead)",
          "deprecated": true
        }
      },
      "required": [
        "redirect_uri",
        "email"
      ]
    },
    "ApiSendEmailResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "example": "Email sent successfully"
        }
      },
      "required": [
        "message"
      ]
    },
    "ApiMagicLinkTokenRequestDto": {
      "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"
            }
          ]
        },
        "device_id": {
          "type": "string",
          "description": "Identifier of the device from which the authentication request originates",
          "maxLength": 80
        },
        "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."
        },
        "code": {
          "type": "string",
          "description": "The code received from the magic link"
        },
        "request_id": {
          "type": "string",
          "description": "The request ID. This is a mandatory parameter if you\u2019ve previously requested to generate a request ID when sending OTP or email link."
        }
      },
      "required": [
        "code"
      ]
    },
    "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"
      ]
    },
    "ApiOtpInitRequestDto": {
      "type": "object",
      "properties": {
        "device_id": {
          "type": "string",
          "description": "Identifier of the device from which the authentication request originates",
          "maxLength": 80
        },
        "channel": {
          "type": "string",
          "enum": [
            "sms",
            "email",
            "direct"
          ],
          "description": "Channel to use to send the OTP. Use `sms` or `email` to deliver the code to the user. Use `direct` to return the code in the response body without sending it \u2014 for example, to deliver it out-of-band as a temporary access code. See [Generate temporary access code](/guides/user/account_recovery.md)."
        },
        "identifier_type": {
          "type": "string",
          "description": "Type of user identifier used for login"
        },
        "identifier": {
          "type": "string",
          "description": "User identifier, which may correspond to the user's email, phone number, username, or user ID. The type of identifier should be specified as the `identifier_type`."
        },
        "email_content": {
          "description": "Texts, logo and color to render email template with, if the channel is `email`",
          "allOf": [
            {
              "$ref": "#/components/schemas/EmailContentAttributes"
            }
          ]
        },
        "custom_sms_input": {
          "description": "Custom SMS message to send, if the channel is `sms`",
          "allOf": [
            {
              "$ref": "#/components/schemas/BaseSmsOtpInput"
            }
          ]
        },
        "approval_data": {
          "type": "object",
          "example": {
            "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
            "sum": "200"
          },
          "description": "Flat object that contains the data that your customer should approve for a transaction signing or custom approval flow. It can contain up to 10 keys, and only alphanumeric characters, underscores, hyphens, and periods. It will be returned as a claim in the ID token upon successful authentication."
        },
        "custom_email": {
          "type": "string",
          "description": "Custom email to send the OTP to, can be different than the user's email (if the channel is `email`)"
        },
        "custom_phone_number": {
          "type": "string",
          "description": "Custom phone number to send the OTP to, can be different than the user's phone number (if the channel is `sms`)"
        },
        "client_attributes": {
          "description": "Client attributes",
          "allOf": [
            {
              "$ref": "#/components/schemas/ClientAttributes"
            }
          ]
        },
        "expires_in": {
          "type": "number",
          "description": "Number of minutes until the OTP expires"
        },
        "generate_request_id": {
          "type": "boolean",
          "description": "The request ID can serve as an additional security identifier for authentication requests. When set to 'false' (by default), the request ID isn't returned. When set to 'true',  Mosaic generates a unique request ID that must be included in the subsequent Authenticate OTP request along with other required parameters.",
          "default": false
        }
      },
      "required": [
        "channel",
        "identifier_type",
        "identifier"
      ]
    },
    "ApiSendOtpResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "readOnly": true,
          "example": "OTP sent"
        },
        "approval_data": {
          "type": "object",
          "readOnly": true,
          "example": {
            "transaction_id": "eFII2y40uB9hQ98nXt3tc1IHkRt8GrRZiqZuRn_59wT",
            "sum": "200"
          },
          "description": "Approval data object, if passed in the request."
        },
        "code": {
          "type": "string",
          "readOnly": true,
          "example": "123456",
          "description": "One time passcode, if the channel is `direct`."
        }
      },
      "required": [
        "message"
      ]
    },
    "ApiOtpTokenRequestDto": {
      "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": {
          "type": "object",
          "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/)."
        },
        "org_id": {
          "type": "string",
          "description": "Organization ID, used for member login in B2B scenarios"
        },
        "client_attributes": {
          "description": "Client attributes",
          "allOf": [
            {
              "$ref": "#/components/schemas/ClientAttributes"
            }
          ]
        },
        "device_id": {
          "type": "string",
          "description": "Identifier of the device from which the authentication request originates",
          "maxLength": 80
        },
        "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."
        },
        "passcode": {
          "type": "string",
          "description": "OTP to validate"
        },
        "identifier_type": {
          "type": "string",
          "description": "Type of user identifier used for sending the OTP"
        },
        "identifier": {
          "type": "string",
          "description": "User identifier that the OTP was sent to"
        },
        "request_id": {
          "type": "string",
          "description": "The request ID. This is a mandatory parameter if you\u2019ve previously requested to generate a request ID when sending OTP or email link."
        }
      },
      "required": [
        "passcode",
        "identifier_type",
        "identifier"
      ]
    },
    "EmailContentAttributes": {
      "type": "object",
      "properties": {
        "subject": {
          "type": "string",
          "description": "The subject of the email"
        },
        "primaryColor": {
          "type": "string",
          "example": "#6981FF",
          "description": "Primary color of the email, specified as a Hex color"
        },
        "base64logo": {
          "type": "string",
          "description": "Base64 encoded image for email logo. The string length must be less than or equal to 20000 characters"
        },
        "headerText": {
          "type": "string",
          "description": "The header of the email"
        },
        "bodyText": {
          "type": "string",
          "description": "The body of the email"
        },
        "linkText": {
          "type": "string",
          "description": "The text of the link button in the email"
        },
        "infoText": {
          "type": "string",
          "description": "Any extra information in the email"
        },
        "footerText": {
          "type": "string",
          "example": "If you didn't request this email, you can safely ignore it.",
          "description": "The footer of the email"
        },
        "senderName": {
          "type": "string",
          "description": "Name of the sender of the email"
        }
      },
      "required": [
        "subject"
      ]
    },
    "ClientAttributes": {
      "type": "object",
      "properties": {
        "user_agent": {
          "type": "string"
        },
        "ip_address": {
          "type": "string"
        }
      }
    },
    "ApiTokenRequestClaims": {
      "type": "object",
      "properties": {
        "id_token": {
          "type": "object"
        },
        "access_token": {
          "type": "object"
        }
      }
    },
    "BaseSmsOtpInput": {
      "type": "object",
      "properties": {
        "custom_message": {
          "type": "string",
          "description": "Message to send, must contain {otp} and {app} placeholders to be replaced with one time password and application name. Limited to 140 characters"
        },
        "sender_id": {
          "type": "string",
          "description": "The sender name that appears as the message sender on recipients devices. Limited to 11 characters. Limited support see https://docs.aws.amazon.com/sns/latest/dg/sns-supported-regions-countries.html"
        }
      }
    }
  }
}