> [!NOTE] > This product will be updated and replaced soon ## Two-Factor Authentication SMS ### Version 5 (Latest) ### Overview The Two-Factor Authentication SMS API enables users to send SMS messages for authentication purposes. By making a `POST` request to the specified endpoint, users can initiate the delivery of an SMS message containing messages or 2FA code to a specified mobile phone number. The API returns a response with a unique session ID and the status of the SMS operation. The status of the SMS can later be checked using a `GET` request. ### Usage #### Endpoints 1. **POST /core/api/sessions/two_factor_auth/sms**: Send an SMS message for two-factor authentication. 2. **GET /core/api/sessions/{session_id}**: Check the status of the sent SMS message. ### Request Details #### **POST Request Method:** **URL:** `https://test-gateway.zignsec.com/core/api/sessions/two_factor_auth/sms` #### **Headers:** - `Authorization`: API key - `Content-Type`: `application/json` - `Accept`: `application/json` #### **Request Body:** The request must include the following parameters in JSON format: | Parameter | Type | Required | Description | |---------------------|--------|----------|------------------------------------------------------------------| | `metadata` | Object | Yes | Contains details about the SMS, such as the sender, message, and recipient. | | `metadata.from` | String | Yes | The sender's phone number, in international format. Example: `+123456789`. | | `metadata.message` | String | Yes | The content of the SMS message. | | `metadata.to` | String | Yes | The recipient's phone number, in international format. Example: `+46701234567`. | | `metadata.max_message_parts` | Integer | Yes | The maximum number of message parts allowed for the SMS. | | `relay_state` | String | No | An internal reference or identifier for tracking purposes. | | `webhook` | String | No | A URL to which webhook notifications will be sent. | #### **Example POST Request:** ```json { "metadata": { "from": "+123456789", "max_message_parts": 1, "message": "ZignSec Testing", "to": "+46701234567" }, "relay_state": "my-internal-user-id", "webhook": "https://webhook.site/" } ``` ### Response Details for POST Request #### **Success Response (200 OK):** A successful response returns the session ID and the initial status of the SMS request. | Parameter | Type | Description | |-------------|--------|--------------------------------------------------| | `data.id` | String | Unique identifier for the SMS session. | | `data.status` | String | Status of the SMS request. Typically `pending`. | #### **Example POST Response:** ```json { "data": { "id": "26f5cc23-dbbb-45bb-a210-2818e70637bd", "status": "pending" } } ``` --- ### Checking SMS Status #### **GET Request Method:** **URL:** `https://test-gateway.zignsec.com/core/api/sessions/{session_id}` Replace `{session_id}` with the session ID received in the POST response. #### **Headers:** - `Authorization`: API key #### **Example GET Request:** ```bash curl --location 'https://test-gateway.zignsec.com/core/api/sessions/26f5cc23-dbbb-45bb-a210-2818e70637bd' \ --header 'Authorization: API key' ``` ### Response Details for GET Request #### **Success Response (200 OK):** A successful response provides the details of the SMS message, including the status. | Parameter | Type | Description | |-------------------------------------|--------|-----------------------------------------------------------------| | `data.id` | String | Unique identifier for the SMS session. | | `data.status` | String | Status of the SMS delivery. Example: `delivered`. | | `data.number_of_message_parts` | Integer| The number of parts the SMS message was divided into. | | `data.request_data.metadata.from` | String | The sender's phone number. | | `data.request_data.metadata.to` | String | The recipient's phone number. | | `data.request_data.metadata.message`| String | The content of the SMS message. | | `data.request_data.relay_state` | String | The internal reference or identifier provided in the POST request. | | `data.request_data.webhook` | String | The webhook URL provided in the POST request. | #### **Example GET Response:** ```json { "data": { "request_data": { "metadata": { "from": "+123456789", "max_message_parts": 1, "message": "ZignSec Testing", "to": "+46701234567" }, "relay_state": "Tulasi_V5_SMS", "webhook": "https://webhook.site/zignsec" }, "id": "26f5cc23-dbbb-45bb-a210-2818e70637bd", "number_of_message_parts": 1, "status": "delivered" } } ``` ### Error Handling Errors may occur due to issues with authentication, invalid request data, or network issues. #### **Common Error Responses:** | Status Code | Error Type | Description | |-------------|------------------------|-------------------------------------------------------------------| | 400 | Invalid Request | The request is malformed, such as a missing or improperly formatted phone number. | | 401 | Unauthorized | The request is missing a valid Authorization token. | | 404 | Not Found | The session ID does not exist. | | 500 | Internal Server Error | An unexpected error occurred on the server. | ### Additional Information - **Authentication**: Ensure that a valid API key is included in the Authorization header. - **Webhook**: If a webhook URL is provided, status updates will be sent to this URL. - **Message Parts**: SMS messages may be split into multiple parts if they exceed the character limit, subject to the `max_message_parts` parameter. ### Testing & Production Environments - **Testing Base URL**: `https://test-gateway.zignsec.com` - **Production Base URL**: `https://gateway.zignsec.com`