API Documentation

RESTful API for TOTP generation and validation

Introduction

2FA.PW API allows you to generate and validate TOTP codes programmatically. All endpoints return JSON responses.

Base URL: https://2fa.pw/api

Rate Limit: 100 requests per minute

Authentication

Currently, no authentication is required. Rate limiting is based on IP address.

API Endpoints

POST /api?endpoint=generate

Generate a TOTP code from a secret key

Request Parameters

Parameter Type Required Description
secret string ✅ Base32 encoded secret key
timeStep integer ❌ Time step in seconds (default: 30)
digits integer ❌ Number of digits (default: 6)

Example Request

cURL
curl -X POST https://2fa.pw/api?endpoint=generate \ -H "Content-Type: application/json" \ -d '{ "secret": "JBSWY3DPEHPK3PXP", "timeStep": 30, "digits": 6 }'

Response

JSON
{ "success": true, "data": { "totp": "123456", "secret": "JBSWY3DPEHPK3PXP", "remaining": 25, "timestamp": 1700000000 } }
POST /api?endpoint=validate

Validate a TOTP code against a secret key

Request Parameters

Parameter Type Required Description
secret string ✅ Base32 encoded secret key
code string ✅ TOTP code to validate
window integer ❌ Time window tolerance (default: 1)

Example Request

cURL
curl -X POST https://2fa.pw/api?endpoint=validate \ -H "Content-Type: application/json" \ -d '{ "secret": "JBSWY3DPEHPK3PXP", "code": "123456" }'

Response

JSON
{ "success": true, "data": { "valid": true, "timestamp": 1700000000 } }
POST /api?endpoint=batch

Generate TOTP codes for multiple secret keys at once

Example Request

cURL
curl -X POST https://2fa.pw/api?endpoint=batch \ -H "Content-Type: application/json" \ -d '{ "secrets": [ "JBSWY3DPEHPK3PXP", "HXDMVJECJJWSRB3H" ] }'

Response

JSON
{ "success": true, "data": { "results": [ { "secret": "JBSWY3DPEHPK3PXP", "totp": "123456", "valid": true }, { "secret": "HXDMVJECJJWSRB3H", "totp": "789012", "valid": true } ], "count": 2, "remaining": 25, "timestamp": 1700000000 } }

Error Responses

When an error occurs, the API returns a JSON response with error details:

JSON
{ "success": false, "error": "Secret key is required", "code": 400 }

Common Error Codes

Code Description
400 Bad Request - Invalid parameters
404 Not Found - Invalid endpoint
429 Too Many Requests - Rate limit exceeded

Code Examples

JavaScript / Node.js
const response = await fetch('https://2fa.pw/api?endpoint=generate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ secret: 'JBSWY3DPEHPK3PXP' }) }); const data = await response.json(); console.log(data.data.totp);
Python
import requests response = requests.post('https://2fa.pw/api?endpoint=generate', json={'secret': 'JBSWY3DPEHPK3PXP'}) data = response.json() print(data['data']['totp'])
PHP
$ch = curl_init('https://2fa.pw/api?endpoint=generate'); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ 'secret' => 'JBSWY3DPEHPK3PXP' ])); curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $data = json_decode($response, true); echo $data['data']['totp'];
cURL
curl -X POST https://2fa.pw/api?endpoint=generate \ -H "Content-Type: application/json" \ -d '{ "secret": "JBSWY3DPEHPK3PXP" }'