> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Verification Session
> Create an identity verification session by generating an authentication token via the iDenfy API with minimal or advanced parameters.
```
POST https://ivs.idenfy.com/api/v2/token
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json
```
***
## Common Examples
Start with these, then customize using the [full parameter reference](#all-parameters) below.
The only required field is `clientId`:
```json theme={"system"}
{
"clientId": "user-123"
}
```
Everything else uses your Dashboard defaults.
Provide user data to cross-check against the document. Mismatches trigger `SUSPECTED` status:
```json theme={"system"}
{
"clientId": "user-123",
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1990-05-15"
}
```
Lock verification to specific countries and document types:
```json theme={"system"}
{
"clientId": "user-123",
"firstName": "John",
"lastName": "Doe",
"country": ["US", "GB", "DE"],
"documents": ["PASSPORT", "ID_CARD"]
}
```
All commonly used fields:
```json theme={"system"}
{
"clientId": "user-123",
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1990-05-15",
"country": "US",
"documents": ["PASSPORT", "ID_CARD"],
"locale": "en",
"expiryTime": 3600,
"sessionLength": 600,
"successUrl": "https://yourapp.com/verified",
"errorUrl": "https://yourapp.com/failed",
"callbackUrl": "https://yourapp.com/webhook"
}
```
### Code Examples
```bash cURL theme={"system"}
curl -X POST https://ivs.idenfy.com/api/v2/token \
-u "YOUR_API_KEY:YOUR_API_SECRET" \
-H "Content-Type: application/json" \
-d '{"clientId": "user-123", "firstName": "John", "lastName": "Doe"}'
```
```python Python theme={"system"}
import requests
response = requests.post(
"https://ivs.idenfy.com/api/v2/token",
auth=("YOUR_API_KEY", "YOUR_API_SECRET"),
json={"clientId": "user-123", "firstName": "John", "lastName": "Doe"}
)
token = response.json()
# token["authToken"] → pass to frontend
# token["redirectUrl"] → or redirect user here
```
```javascript Node.js theme={"system"}
const response = await fetch("https://ivs.idenfy.com/api/v2/token", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Basic " + btoa("YOUR_API_KEY:YOUR_API_SECRET"),
},
body: JSON.stringify({ clientId: "user-123", firstName: "John", lastName: "Doe" }),
});
const token = await response.json();
// token.authToken → pass to frontend
// token.redirectUrl → or redirect user here
```
```php PHP theme={"system"}
$ch = curl_init("https://ivs.idenfy.com/api/v2/token");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_USERPWD, "YOUR_API_KEY:YOUR_API_SECRET");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"clientId" => "user-123", "firstName" => "John", "lastName" => "Doe"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$token = json_decode(curl_exec($ch), true);
```
```ruby Ruby theme={"system"}
require "net/http"
require "json"
uri = URI("https://ivs.idenfy.com/api/v2/token")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request.basic_auth("YOUR_API_KEY", "YOUR_API_SECRET")
request.content_type = "application/json"
request.body = { clientId: "user-123", firstName: "John", lastName: "Doe" }.to_json
token = JSON.parse(http.request(request).body)
```
***
## Response
```json theme={"system"}
{
"message": "Token created successfully",
"authToken": "pgYQX0z2T8mtcpNj9I20uWVCLKNuG0vgr12f0wAC",
"scanRef": "ec6a7108-8c26-11e9-9758-309c231b1bac",
"clientId": "user-123",
"firstName": "JOHN",
"lastName": "DOE",
"redirectUrl": "https://ivs.idenfy.com/api/v2/redirect?authToken=pgYQX0z2T8...",
"digitString": null,
"expiryTime": 3600,
"sessionLength": 600
}
```
**Key response fields:**
| Field | Use it for |
| ------------- | ----------------------------------------------------------------- |
| `authToken` | Pass to iFrame, SDK, or redirect URL |
| `redirectUrl` | Redirect user here for hosted verification |
| `scanRef` | Unique verification ID — store this in your database |
| `digitString` | 8-digit code for mobile app (only if `generateDigitString: true`) |
***
## What to Do Next
After generating the token, send your user to verification:
| Method | Code | When to use |
| --------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| **Redirect** | `window.location.href = token.redirectUrl` | Simplest. User leaves your site. |
| **iFrame** | `