> [!NOTE]
> This product will be updated and replaced soon
### Two-Factor Authentication API - Email Verification
This document provides a comprehensive guide to using ZignSec's **Two-Factor Authentication (2FA)** API for email-based authentication.
---
## **POST** `/core/api/sessions/two_factor_auth/email`
### Description
Initiates a two-factor authentication session to verify a user’s email address. The API returns a unique session ID and a `redirect_url` for the user to complete the verification process.
---
### **Request Headers**
|Header Name|Required|Description|
|---|---|---|
|`accept`|Yes|Specifies the expected response format. Use `application/json`.|
|`Content-Type`|Yes|Specifies the request body format. Use `application/json`.|
|`x-csrf-token`|Yes|CSRF token for security purposes.|
|`Authorization`|Yes|API key for authenticating the request.|
---
### **Request Body**
|Field Name|Required|Type|Description|
|---|---|---|---|
|`locale`|Yes|String|Language for the session. Example: `"En"` for English.|
|`metadata`|Yes|Object|Contains email address information.|
|`metadata.email_address`|Yes|String|Email address to verify. Example: `"
[email protected]"`.|
|`redirect_failure`|Yes|String|URL to redirect the user if verification fails.|
|`redirect_success`|Yes|String|URL to redirect the user upon successful verification.|
|`relay_state`|No|String|Custom state information to track the session.|
|`webhook`|No|String|URL to receive updates about the session.|
---
### **Example Request**
```bash
curl --location 'https://test-gateway.zignsec.com/core/api/sessions/two_factor_auth/email' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-csrf-token: XAoXAwglHykhAEkcUGp0T0A_BAgnUgMvoSUgkouQSjzof3Y87HcYu8lb' \
--header 'Authorization: API key' \
--data '{
"locale": "En",
"metadata": {
"email_address": "
[email protected]"
},
"redirect_failure": "https://my_failure_url.com",
"redirect_success": "https://my_success_url.com",
"relay_state": "Email_2FA_Session",
"webhook": "https://webhook.site/zignsec"
}'
```
---
### **Example Response**
```json
{
"data": {
"id": "d1234567-89ab-cdef-0123-456789abcdef",
"redirect_url": "https://test-gateway.zignsec.com/2fa-ui/2fa/email/d1234567-89ab-cdef-0123-456789abcdef",
"status": "pending"
}
}
```
|Field Name|Type|Example|Description|
|---|---|---|---|
|`data.id`|String|`"d1234567-89ab-cdef-0123-456789abcdef"`|Unique identifier for the session.|
|`data.redirect_url`|String|`"https://test-gateway.zignsec.com/2fa-ui/2fa/email/..."`|URL for the user to complete the verification process.|
|`data.status`|String|`"pending"`|Current status of the session.|
---
### **Verification Flow**
1. **Initiate the Session**: Send a `POST` request to the `/two_factor_auth/email` endpoint with the user’s email address.
2. **User Navigates to the Verification URL**: Direct the user to the `redirect_url` provided in the response.
3. **User Receives Email with Code**: The user receives an email containing a unique verification code.
4. **User Enters the Code**: The user enters the verification code on the browser interface.
5. **Redirect Based on Outcome**:
- **Success**: If the code is correct, the user is redirected to the `redirect_success` URL.
- **Failure**: If the code is incorrect or the process fails, the user is redirected to the `redirect_failure` URL.
---
### **Check Session Status**
You can retrieve the status of an email verification session using the session ID.
#### **GET** `/core/api/sessions/{session_id}`
|Header Name|Required|Description|
|---|---|---|
|`Authorization`|Yes|API key for authenticating the request.|
---
#### **Example Request**
```bash
curl --location 'https://test-gateway.zignsec.com/core/api/sessions/d1234567-89ab-cdef-0123-456789abcdef' \
--header 'Authorization: API key'
```
---
#### **Example Response**
```json
{
"data": {
"request_data": {
"locale": "En",
"metadata": {
"email_address": "
[email protected]"
},
"redirect_failure": "https://my_failure_url.com",
"redirect_success": "https://my_success_url.com",
"relay_state": "Email_2FA_Session",
"webhook": "https://webhook.site/zignsec"
},
"id": "d1234567-89ab-cdef-0123-456789abcdef",
"email_address": "
[email protected]",
"status": "finished"
}
}
```
|Field Name|Type|Example|Description|
|---|---|---|---|
|`data.request_data`|Object|`{...}`|Contains initial request details.|
|`data.id`|String|`"d1234567-89ab-cdef-0123-456789abcdef"`|Unique identifier for the session.|
|`data.email_address`|String|`"
[email protected]"`|Email address associated with the session.|
|`data.status`|String|`"finished"`|Status of the session (`pending`, `finished`, `failed`, `cancelled`).|
---
### **Session Status Values**
|Status|Description|
|---|---|
|`pending`|The session is ongoing.|
|`finished`|The session completed successfully.|
|`failed`|The session failed.|
|`cancelled`|The session was cancelled.|
---
This flow ensures secure email-based two-factor authentication for verifying user email addresses.