> [!NOTE] > This product will be updated and replaced soon ## Two-Factor Authentication Phone This documentation provides a step-by-step guide to implementing SMS-based phone verification using ZignSec’s 2FA API. --- ### 1. Initiate 2FA Session Send a `POST` request to initiate the 2FA session. #### Endpoint `POST https://test-gateway.zignsec.com/core/api/sessions/two_factor_auth/phone` #### Headers |Header Name|Value|Description| |---|---|---| |`accept`|`application/json`|Specifies the expected response format.| |`Content-Type`|`application/json`|Specifies the request body format.| |`x-csrf-token`|`<Your CSRF token>`|CSRF token for security purposes.| |`Authorization`|`API key`|API key for authentication.| #### Request Body Parameters |Parameter|Type|Example|Description| |---|---|---|---| |`locale`|String|`"En"`|Language for the 2FA session (e.g., "En" for English).| |`metadata`|Object|`{ "phone_number": "+46703339954" }`|Contains phone number information.| |`redirect_failure`|String|`"https://my_failure_url.com"`|URL to redirect to if verification fails.| |`redirect_success`|String|`"https://my_success_url.com"`|URL to redirect to upon successful verification.| |`relay_state`|String|`"Tulasi_V5_SMS"`|Custom state information to identify the session.| |`webhook`|String|`"https://webhook.site/zignsec"`|URL for receiving session status updates.| #### Example Request ```bash curl --location 'https://test-gateway.zignsec.com/core/api/sessions/two_factor_auth/phone' \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --header 'x-csrf-token: XAoXAwglHykhAEkcUGp0T0A_BAgnUgMvoSUgkouQSjzof3Y87HcYu8lb' \ --header 'Authorization: API key' \ --data '{ "locale": "En", "metadata": { "phone_number": "+46703339954" }, "redirect_failure": "https://my_failure_url.com", "redirect_success": "https://my_success_url.com", "relay_state": "Tulasi_V5_SMS", "webhook": "https://webhook.site/zignsec" }' ``` #### Example Response ```json { "data": { "id": "b653e2c9-0138-434e-99c9-c9333cfb1129", "redirect_url": "https://test-gateway.zignsec.com/2fa-ui/2fa/phone/b653e2c9-0138-434e-99c9-c9333cfb1129", "status": "pending" } } ``` #### Response Fields |Field Name|Type|Example|Description| |---|---|---|---| |`data.id`|String|`"b653e2c9-0138-434e-99c9-c9333cfb1129"`|Unique identifier for the session.| |`data.redirect_url`|String|`"https://test-gateway.zignsec.com/2fa-ui/2fa/phone/..."`|URL for user to initiate the 2FA process.| |`data.status`|String|`"pending"`|Current status of the session.| --- ### 2. User Action - Phone Verification 1. **User Navigates to Verification URL** ![[phone-sendSms.jpg]] The user is directed to the `redirect_url` where they can initiate verification. 2. **User Receives SMS Code** The user receives a 5-digit SMS code sent to their specified phone number. 3. **User Enters SMS Code** 1. ![[phone-enterCode.jpg]] The user enters the code on the ZignSec verification page. 2. ![[phone-tryAgain.jpg]] If the user enters wrong code they will be prompted to send a new SMS code. 3. ![[phone-cancel.jpg]] On cancel this screen is shown. 4. **Redirection Based on Verification Result** ![[phone-successURL.jpg]] - **Success**: If the code is correct, the user is redirected to `redirect_success`. - **Failure**: If the code is incorrect, the user is redirected to `redirect_failure`. --- ### 3. Check 2FA Session Status and Final result Use the session ID to programmatically check the status of the 2FA session by sending a `GET` request. #### Endpoint `GET https://test-gateway.zignsec.com/core/api/sessions/{session_id}` #### Headers |Header Name|Value|Description| |---|---|---| |`Authorization`|`API key`|API key for authentication.| #### Example Request ``` `curl --location 'https://test-gateway.zignsec.com/core/api/sessions/55c20771-9d75-4241-8e0f-94d3a37671ca' \ --header 'Authorization: API key'` ``` #### Example Response ```json { "data": { "request_data": { "locale": "En", "metadata": { "phone_number": "+46703339954" }, "redirect_failure": "https://my_failure_url.com", "redirect_success": "https://my_success_url.com", "relay_state": "Tulasi_V5_SMS", "webhook": "https://webhook.site/zignsec" }, "id": "55c20771-9d75-4241-8e0f-94d3a37671ca", "phone_number": "+46703339954", "status": "accepted" } } ``` #### Response Fields | Field Name | Type | Example | Description | | ------------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------------- | | `data.request_data` | Object | `{...}` | Contains initial request details. | | `data.id` | String | `"55c20771-9d75-4241-8e0f-94d3a37671ca"` | Unique identifier for the session. | | `data.phone_number` | String | `"+46703339954"` | Phone number associated with the session. | | `data.status` | String | `"accepted"` | Current session status (`pending`, `accepted`, `failed`, `cancelled`). | #### Status Values | Status | Description | | ----------- | ----------------------------------- | | `pending` | The session is ongoing. | | `finished` | The session completed successfully. | | `failed` | The session failed. | | `cancelled` | The session was cancelled. |