Skip to content
Technical Documentation Lab

Auth API Quickstart

SecureAuth — Quickstart Guide

Section titled “SecureAuth — Quickstart Guide”

Get up and running with MFA enrollment and verification in minutes.

Prerequisites

Section titled “Prerequisites”
  • A valid SecureAuth account
  • Your Bearer Token (issued from the developer dashboard)
  • A TOTP-compatible authenticator app (e.g., Google Authenticator, Authy)

Authentication

Section titled “Authentication”

All requests require an Authorization header containing your Bearer Token.

Authorization: Bearer <YOUR_TOKEN>

Endpoints

Section titled “Endpoints”

POST /v1/mfa/enroll

Section titled “POST /v1/mfa/enroll”

Enrolls a user in TOTP-based multi-factor authentication.

Enrollment Request

Section titled “Enrollment Request”
POST /v1/mfa/enroll HTTP/1.1
Host: api.secureauth.io
Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json


{
  "user_id": "usr_01HXYZ",
  "method": "totp"
}

Enrollment Response — 200 OK

Section titled “Enrollment Response — 200 OK”
{
  "enrollment_id": "enr_09ABCD",
  "totp_uri": "otpauth://totp/SecureAuth:usr_01HXYZ?secret=SECRET32",
  "qr_code_url": "https://api.secureauth.io/qr/enr_09ABCD.png"
}

Enrollment Response Fields

Section titled “Enrollment Response Fields”
FieldTypeDescription
enrollment_idstringUnique identifier for this enrollment
totp_uristringOTP Auth URI for authenticator apps
qr_code_urlstringURL to the scannable QR code image

POST /v1/mfa/verify

Section titled “POST /v1/mfa/verify”

Verifies a TOTP code submitted by the user.

Verification Request

Section titled “Verification Request”
POST /v1/mfa/verify HTTP/1.1
Host: api.secureauth.io
Authorization: Bearer <YOUR_TOKEN>
Content-Type: application/json


{
  "enrollment_id": "enr_09ABCD",
  "totp_code": "123456"
}

Verification Response — 200 OK

Section titled “Verification Response — 200 OK”
{
  "verified": true,
  "session_token": "sess_XYZ789..."
}

Response — 401 Unauthorized

Section titled “Response — 401 Unauthorized”
{
  "verified": false,
  "error": "invalid_totp_code"
}

Verification Response Fields

Section titled “Verification Response Fields”
FieldTypeDescription
enrollment_idstringEnrollment ID returned at enroll step
totp_codestring6-digit code from your authenticator
verifiedbooleantrue if verification succeeded
session_tokenstringSession token issued on success

Error Codes

Section titled “Error Codes”
CodeStatusDescription
invalid_token401Bearer Token is missing or invalid
user_not_found404The specified user_id not found
invalid_totp_code401TOTP code is incorrect or expired
enrollment_not_found404No enrollment matches that ID

Next Steps

Section titled “Next Steps”