Scripe
SCRIPEDOCS

User Authentication API

User registration, email/phone verification, login, external OAuth, password reset, 2FA, and profile management.

The User Authentication API handles self-service authentication for end-users. Unlike the Admin Auth API, it includes registration, email/phone verification, external OAuth login, and password reset flows.

Base Configuration

SettingValueDescription
Base URL/api/v1/auth/userAll regular user (client) auth endpoints base path
Profile Base URL/api/v1/UsersUser profile management endpoints
Auth RequiredPartialLogin, register, external-login, verification, refresh, and password-reset are public; others require Bearer token
Rate LimitsLogin (10 req/5 min), password-reset, otp-verificationProtects client-facing auth endpoints
Content-Typeapplication/jsonAll requests and responses use JSON format

Registration

MethodEndpointDescriptionAuth
POST/api/v1/auth/user/registerRegister a new user account with email, password, and tenant. Sends verification email.🔒 Required
POST /api/v1/auth/user/register — Request BodyJSON
{
  "username": "alicejohnson",
  "password": "SecureP@ssword1!",
  "email": "alice@example.com",
  "phoneNumber": "+1234567890",
  "tenantCode": "ACME" // Public tenant workspace code
}

Login

MethodEndpointDescriptionAuth
POST/api/v1/auth/user/loginAuthenticate user with email and password. Returns JWT access + refresh tokens.🔒 Required
POST/api/v1/auth/user/login/{provider}Initiate SSO or OAuth2 authentication flow with an external identity provider.🔒 Required
POST /api/v1/auth/user/login — RequestJSON
{
  "username": "alicejohnson", // Can be email or username
  "password": "SecureP@ssword1!",
  "deviceInfo": "Mozilla/5.0 Chrome/120.0.0" // Optional
}

Email & Phone Verification

MethodEndpointDescriptionAuth
POST/api/v1/auth/user/verify-emailVerify email address using a 6-digit OTP code sent to the user's email.🔒 Required
POST/api/v1/auth/user/verify-phoneVerify phone number using a 6-digit OTP code sent via SMS.🔒 Required
POST/api/v1/auth/user/send-email-verificationDispatch a verification token to the user's primary registered email address.🔒 Required
POST/api/v1/auth/user/send-phone-verificationSend an SMS one-time verification passcode to the user's registered mobile number.🔒 Required
POST /api/v1/auth/user/verify-email — Request & ResponseJSON
// Request Body
{
  "email": "alice@example.com",
  "code": "654321"
}

// Response (200 OK)
{
  "message": "Email verified successfully"
}

Password Reset

MethodEndpointDescriptionAuth
POST/api/v1/auth/user/request-password-resetRequest a password reset code. Always returns success to prevent email enumeration.🔒 Required
POST/api/v1/auth/user/reset-passwordReset password using the 6-digit code from forgot-password.🔒 Required
POST /api/v1/auth/user/request-password-reset — Request & ResponseJSON
// Request
{
  "email": "alice@example.com"
}

// Response (202 Accepted)
{
  "sent": true,
  "retryAfterSeconds": null
}

Token Management

MethodEndpointDescriptionAuth
POST/api/v1/auth/user/refreshExchange a valid refresh token for a new token pair. Single-use rotation.🔒 Required
POST/api/v1/auth/user/logoutRevoke all refresh tokens and end the session.🔒 Required

User Two-Factor Authentication

MethodEndpointDescriptionAuth
POST/api/v1/auth/user/2fa/enableGenerate TOTP secret and QR code for authenticator app setup.🔒 Required
POST/api/v1/auth/user/2fa/confirmConfirm 2FA by verifying the first TOTP code. Returns 10 backup codes.🔒 Required
POST/api/v1/auth/user/2fa/verifyComplete login by verifying the TOTP code with the 2FA session token.🔒 Required
POST/api/v1/auth/user/2fa/disableDisable 2FA for the current user. Requires valid bearer token.🔒 Required
POST /2fa/enable — ResponseJSON
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUri": "otpauth://totp/SCRIPE:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=SCRIPE",
  "qrCodeBase64": "data:image/png;base64,iVBORw..."
}

External Authentication

MethodEndpointDescriptionAuth
GET/api/v1/auth/user/external-loginsList all third-party social and enterprise login providers linked to this user.🔒 Required
POST/api/v1/auth/user/external-logins/linkAssociate an external social or OIDC login token with the user's profile.🔒 Required
DELETE/api/v1/auth/user/external-logins/{externalLoginId}Remove an external identity link from the user account.🔒 Required

User Profile

MethodEndpointDescriptionAuth
GET/api/v1/Users/meGet the authenticated user's profile, including tenant and verification status.🔒 Required
GET /api/v1/Users/me — ResponseJSON
{
  "id": "user-uuid-12345",
  "username": "alicejohnson",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Johnson",
  "phoneNumber": "+1234567890",
  "avatarUrl": "/uploads/avatars/user1.png",
  "isActive": true,
  "tenantId": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "emailVerified": true,
  "phoneVerified": false,
  "createdAt": "2026-06-25T14:20:00Z"
}

Endpoint Summary

EndpointMethodAuthRate Limit
/api/v1/auth/user/registerPOSTNoneglobal
/api/v1/auth/user/loginPOSTNoneauth
/api/v1/auth/user/login/{provider}POSTNoneauth
/api/v1/auth/user/verify-emailPOSTNoneotp
/api/v1/auth/user/verify-phonePOSTNoneotp
/api/v1/auth/user/send-email-verificationPOSTNoneotp
/api/v1/auth/user/send-phone-verificationPOSTNoneotp
/api/v1/auth/user/request-password-resetPOSTNonepassword-reset
/api/v1/auth/user/reset-passwordPOSTNoneglobal
/api/v1/auth/user/refreshPOSTNonetoken-refresh
/api/v1/auth/user/logoutPOSTBearerglobal
/api/v1/auth/user/2fa/enablePOSTBearerglobal
/api/v1/auth/user/2fa/confirmPOSTBearerglobal
/api/v1/auth/user/2fa/verifyPOSTNoneauth
/api/v1/auth/user/2fa/disablePOSTBearerglobal
/api/v1/auth/user/external-loginsGETBearerglobal
/api/v1/auth/user/external-logins/linkPOSTBearerglobal
/api/v1/auth/user/external-logins/{externalLoginId}DELETEBearerglobal
/api/v1/Users/meGETBearerglobal
PreviousAuthentication API (Admin)NextAdmin Management API