B2B Integration API

To integrate TsByin 2FA into your external applications (e-commerce, internal dashboards, etc.), you can use our Server-to-Server provisioning API.

1. Authentication

All integration endpoints require authentication via an API Key. You can generate an API Key from the Integrations (B2B) tab in the TsByin 2FA dashboard.

Send the API Key in the Authorization header as a Bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx

---

2. Provisioning a new 2FA Secret

Use this endpoint to generate a new TOTP secret for a user in your application. We will store it unencrypted on our Edge Database so that we can verify codes on your behalf.

Endpoint: POST https://api-2fa.tsbyinchei.workers.dev/v1/secrets

Request Body:

{
  "project_id": "prj_abc123...",
  "user_identifier": "[email protected]",
  "issuer": "My E-commerce App"
}

Response:

{
  "success": true,
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/My%20E-commerce%20App:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=My%20E-commerce%20App&algorithm=SHA1&digits=6&period=30"
}

Note: You should use the otpauth_url to generate a QR Code using a library like qrcode on your frontend, so your users can scan it into their Google Authenticator or Authy app.

---

3. Verifying a 2FA Code

When a user logs into your application, they will provide a 6-digit code. Send this code to our verification endpoint.

Endpoint: POST https://api-2fa.tsbyinchei.workers.dev/v1/verify

Request Body:

{
  "project_id": "prj_abc123...",
  "user_identifier": "[email protected]",
  "totp_code": "123456"
}

Response (Success):

{
  "success": true,
  "message": "Verified"
}

Response (Error):

{
  "success": false,
  "error_code": "INVALID_CODE",
  "attempts_left": 3
}

---

Testing with Postman

1. Create a Project in the TsByin 2FA App.
2. Copy the Project ID and API Key.
3. Call POST /v1/secrets using Postman with your API Key to get a secret.
4. Import the secret into an Authenticator App (or use a CLI tool) to generate a 6-digit code.
5. Call POST /v1/verify using Postman with the API Key and the generated 6-digit code.