QrioTagQrioTag Docs
API Reference

Authentication API

Register, login, manage tokens, two-factor authentication, API keys, sessions, and account management endpoints.

All authentication endpoints are under /auth. Most require no authentication (register, login, password reset) while account management endpoints require a valid access token.

Register

POST /api/v1/auth/register — No auth

Login

POST /api/v1/auth/login — No auth

Refresh Token

POST /api/v1/auth/refresh — No auth

2FA Setup

POST /api/v1/auth/enable-2fa — Required

Account (me)

GET / PATCH / DELETE /api/v1/auth/me — Required

API Keys

GET / POST / DELETE /api/v1/auth/api-keys — Required

Sessions

GET / DELETE /api/v1/auth/sessions — Required

Register

Create a new user account.

Rate limited

This endpoint is limited to 5 requests per hour per IP address.

POST /api/v1/auth/register — Auth: None

Request body

FieldTypeRequiredDescription
emailstringYesValid email address
passwordstringYesMinimum 8 characters, must include uppercase, lowercase, and number
firstNamestringYesFirst name
lastNamestringYesLast name
  curl -X POST https://api.qriotag.global/api/v1/auth/register \
    -H "Content-Type: application/json" \
    -d '{
      "email": "jane@example.com",
      "password": "SecurePass123",
      "firstName": "Jane",
      "lastName": "Doe"
    }'

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "emailVerified": false
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Login

Authenticate with email and password. Returns access and refresh tokens.

POST /api/v1/auth/login — Auth: None

Request body

FieldTypeRequiredDescription
emailstringYesAccount email
passwordstringYesAccount password
twoFactorCodestringNo6-digit TOTP code if 2FA is enabled
  curl -X POST https://api.qriotag.global/api/v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "jane@example.com",
      "password": "SecurePass123"
    }'

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "role": "USER",
      "twoFactorEnabled": false
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Two-factor authentication

If the user has 2FA enabled and no twoFactorCode is provided, the response will return { "success": false, "error": { "code": "TWO_FACTOR_REQUIRED" } } with HTTP 403. Resend the request with the TOTP code.

Refresh Token

Exchange a valid refresh token for a new access token.

POST /api/v1/auth/refresh — Auth: None

Request body

FieldTypeRequiredDescription
refreshTokenstringYesThe refresh token from login
  curl -X POST https://api.qriotag.global/api/v1/auth/refresh \
    -H "Content-Type: application/json" \
    -d '{
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    }'

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Logout

Invalidate the current session and refresh token.

POST /api/v1/auth/logout — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/auth/logout \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}

Forgot Password

Send a password reset email to the specified address.

Rate limited

This endpoint is limited to 3 requests per hour per IP address.

POST /api/v1/auth/forgot-password — Auth: None

Request body

FieldTypeRequiredDescription
emailstringYesThe account email address
  curl -X POST https://api.qriotag.global/api/v1/auth/forgot-password \
    -H "Content-Type: application/json" \
    -d '{ "email": "jane@example.com" }'

Response

{
  "success": true,
  "data": {
    "message": "If that email exists, a reset link has been sent."
  }
}

Security note

The response is always the same whether the email exists or not, to prevent email enumeration.

Reset Password

Set a new password using the token from the reset email.

POST /api/v1/auth/reset-password — Auth: None

Request body

FieldTypeRequiredDescription
tokenstringYesReset token from email link
passwordstringYesNew password (same rules as registration)
  curl -X POST https://api.qriotag.global/api/v1/auth/reset-password \
    -H "Content-Type: application/json" \
    -d '{
      "token": "rst_abc123...",
      "password": "NewSecurePass456"
    }'

Response

{
  "success": true,
  "data": {
    "message": "Password reset successfully"
  }
}

Get Current User

Retrieve the authenticated user's profile.

GET /api/v1/auth/me — Auth: Required

  curl https://api.qriotag.global/api/v1/auth/me \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "role": "USER",
    "emailVerified": true,
    "twoFactorEnabled": false,
    "subscription": "FREE",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Update Profile

Update the authenticated user's profile information.

PATCH /api/v1/auth/me — Auth: Required

Request body

FieldTypeRequiredDescription
firstNamestringNoUpdated first name
lastNamestringNoUpdated last name
phonestringNoPhone number
  curl -X PATCH https://api.qriotag.global/api/v1/auth/me \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "firstName": "Janet",
      "phone": "+1234567890"
    }'

Response

{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "jane@example.com",
    "firstName": "Janet",
    "lastName": "Doe",
    "phone": "+1234567890"
  }
}

Delete Account (GDPR)

Permanently delete the authenticated user's account and all associated data.

Destructive action

This action is irreversible. All tags, profiles, messages, and order history will be permanently deleted.

DELETE /api/v1/auth/me — Auth: Required

  curl -X DELETE https://api.qriotag.global/api/v1/auth/me \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "Account deleted successfully"
  }
}

Export Account Data (GDPR)

Download all data associated with the authenticated user's account.

GET /api/v1/auth/me/export — Auth: Required

  curl https://api.qriotag.global/api/v1/auth/me/export \
    -H "Authorization: Bearer <token>" \
    -o my-data.json

Response

{
  "success": true,
  "data": {
    "user": { "id": "usr_abc123", "email": "jane@example.com", "..." : "..." },
    "tags": [],
    "orders": [],
    "messages": [],
    "notifications": [],
    "exportedAt": "2025-06-01T12:00:00.000Z"
  }
}

Change Password

Change the password for the authenticated user.

POST /api/v1/auth/change-password — Auth: Required

Request body

FieldTypeRequiredDescription
currentPasswordstringYesCurrent password
newPasswordstringYesNew password
  curl -X POST https://api.qriotag.global/api/v1/auth/change-password \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "currentPassword": "SecurePass123",
      "newPassword": "EvenMoreSecure456"
    }'

Response

{
  "success": true,
  "data": {
    "message": "Password changed successfully"
  }
}

Enable Two-Factor Authentication

Begin the 2FA setup process. Returns a QR code URL and secret for authenticator apps.

POST /api/v1/auth/enable-2fa — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/auth/enable-2fa \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "qrCodeUrl": "data:image/png;base64,iVBORw0KGgo...",
    "secret": "JBSWY3DPEHPK3PXP"
  }
}

Next step

After scanning the QR code with an authenticator app, call POST /auth/verify-2fa with the generated code to complete setup.

Verify Two-Factor Authentication

Complete 2FA setup by verifying a code from the authenticator app.

POST /api/v1/auth/verify-2fa — Auth: Required

Request body

FieldTypeRequiredDescription
codestringYes6-digit TOTP code from authenticator app
  curl -X POST https://api.qriotag.global/api/v1/auth/verify-2fa \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{ "code": "123456" }'

Response

{
  "success": true,
  "data": {
    "message": "Two-factor authentication enabled",
    "backupCodes": [
      "abc12345",
      "def67890",
      "ghi11223"
    ]
  }
}

Send Verification Email

Resend the email verification link.

POST /api/v1/auth/send-verification — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/auth/send-verification \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "Verification email sent"
  }
}

Verify Email

Confirm the user's email address using the token from the verification email.

POST /api/v1/auth/verify-email — Auth: None

Request body

FieldTypeRequiredDescription
tokenstringYesVerification token from email
  curl -X POST https://api.qriotag.global/api/v1/auth/verify-email \
    -H "Content-Type: application/json" \
    -d '{ "token": "vrf_abc123..." }'

Response

{
  "success": true,
  "data": {
    "message": "Email verified successfully"
  }
}

API Keys

Sessions

Was this page helpful?

Edit on GitHub

API Reference

Previous Page

Tags API

Next Page

On this page

RegisterRequest bodyResponseLoginRequest bodyResponseRefresh TokenRequest bodyResponseLogoutResponseForgot PasswordRequest bodyResponseReset PasswordRequest bodyResponseGet Current UserResponseUpdate ProfileRequest bodyResponseDelete Account (GDPR)ResponseExport Account Data (GDPR)ResponseChange PasswordRequest bodyResponseEnable Two-Factor AuthenticationResponseVerify Two-Factor AuthenticationRequest bodyResponseSend Verification EmailResponseVerify EmailRequest bodyResponseAPI KeysResponseResponseResponseSessionsResponseResponse
Authentication API | QrioTag Docs