Authentication API (Admin)

Admin authentication endpoints — login, refresh, logout, 2FA, profile management, and security logs.

The Authentication API handles admin-panel authentication for dashboard users. Unlike the User Auth API, it includes two-factor authentication management, admin profile endpoints, and security log access. All endpoints use the /api/v1/auth base path.

Base Configuration

Setting	Value	Description
Base URL	/api/v1/auth/admin	All admin auth endpoints base path
Profile Base URL	/api/v1/Admins	Admin self-service profile and password endpoints
Auth Required	Partial	Login, refresh, 2FA verify, discover-workspaces, and password reset are public; others require Bearer token
Rate Limits	Login (10 req/5 min), token-refresh, password-reset	Protects authentication flows from brute force
Content-Type	application/json (multipart/form-data for avatar)	All request and response payloads

Method	Endpoint	Description	Auth
POST	`/api/v1/auth/admin/login`	Authenticate admin with email/password. Returns JWT access + refresh tokens.	🔒 Required
POST	`/api/v1/auth/admin/refresh`	Exchange a valid refresh token for a new access + refresh token pair. Single-use rotation.	🔒 Required
POST	`/api/v1/auth/admin/discover-workspaces`	Discover all accessible workspaces and organizations associated with user credentials.	🔒 Required
POST	`/api/v1/auth/admin/logout`	Revoke all refresh tokens for the authenticated user. Access token remains valid until expiry.	🔒 Required

POST /api/v1/auth/admin/login — Request BodyJSON

{
  "identifier": "admin@example.com",
  "password": "P@ssw0rd123!",
  "tenantId": "f8e7d6c5-b4a3-2190-fedc-ba0987654321", // Optional
  "deviceInfo": "Mozilla/5.0 Chrome/120.0.0", // Optional
  "isPlatformAdmin": false
}

List all active sessions with device info, IP address, and last activity.

Method	Endpoint	Description	Auth
GET	`/api/v1/auth/admin/sessions`	List all active sessions with device info, IP address, and last activity.	🔒 Required
DELETE	`/api/v1/auth/admin/sessions/{tokenId}`	Revoke a specific session by ID, forcing re-authentication on that device.	🔒 Required
POST	`/api/v1/auth/admin/sessions/revoke-all`	Revoke all active sessions and refresh tokens across all devices simultaneously.	🔒 Required

GET /api/v1/auth/admin/sessions — ResponseJSON

[
  {
    "tokenId": "session-token-uuid-1",
    "deviceInfo": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0",
    "ipAddress": "192.168.1.50",
    "isCurrent": true,
    "lastActiveAt": "2026-06-28T11:30:00Z",
    "createdAt": "2026-06-28T09:00:00Z"
  },
  {
    "tokenId": "session-token-uuid-2",
    "deviceInfo": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2) Safari/604.1",
    "ipAddress": "172.56.21.9",
    "isCurrent": false,
    "lastActiveAt": "2026-06-27T18:45:00Z",
    "createdAt": "2026-06-25T14:20:00Z"
  }
]

Two-Factor Authentication

SCRIPE supports TOTP-based 2FA using authenticator apps (Google Authenticator, Authy, Microsoft Authenticator). Once enabled, login returns a session token instead of access tokens — the client must verify the TOTP code to complete authentication.

Method	Endpoint	Description	Auth
POST	`/api/v1/auth/admin/2fa/enable`	Generate a TOTP secret and QR code URI for setup in an authenticator app.	🔒 Required
POST	`/api/v1/auth/admin/2fa/confirm`	Confirm 2FA setup by verifying the first TOTP code. Returns backup codes.	🔒 Required
POST	`/api/v1/auth/admin/2fa/verify`	Complete login by verifying the TOTP code with the 2FA session token.	🔒 Required
POST	`/api/v1/auth/admin/2fa/disable`	Disable 2FA for the current admin account. Requires valid bearer token.	🔒 Required
POST	`/api/v1/auth/admin/2fa/backup-codes/regenerate`	Regenerate a new set of 10 backup codes. Previous codes are invalidated.	🔒 Required

POST /2fa/enable — ResponseJSON

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUri": "otpauth://totp/SCRIPE:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=SCRIPE",
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}

Impersonation

Method	Endpoint	Description	Auth
POST	`/api/v1/auth/admin/impersonate/{id}`	Start impersonating another admin. Receive their JWT with your audit trail attached.	🔒 Required
POST	`/api/v1/auth/admin/stop-impersonation`	Stop impersonation and return to your original admin session.	🔒 Required

POST /impersonate/{id} — ResponseJSON

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Impersonated Admin JWT
  "refreshToken": "impersonation_refresh_token_here...",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "requiresTwoFactor": false,
  "user": {
    "id": "target-admin-uuid",
    "email": "target@example.com",
    "role": "TenantAdmin",
    "tenantId": "target-tenant-uuid",
    "impersonatorAdminId": "superadmin-uuid" // Auditing trail marker
  }
}

External Authentication

Method	Endpoint	Description	Auth
GET	`/api/v1/auth/admin/external-logins`	List external SSO and social identity provider connections linked to this account.	🔒 Required
POST	`/api/v1/auth/admin/external-logins/link`	Link a third-party OAuth/OIDC credential to the authenticated admin account.	🔒 Required
DELETE	`/api/v1/auth/admin/external-logins/{externalLoginId}`	Unlink an external authentication provider from the account.	🔒 Required

GET /external-logins — ResponseJSON

[
  {
    "id": "external-login-uuid-1",
    "providerName": "Google",
    "providerKey": "1048596048593028",
    "email": "admin@gmail.com",
    "displayName": "John Google",
    "linkedAt": "2026-06-20T10:00:00Z",
    "lastUsedAt": "2026-06-28T08:30:00Z"
  }
]

Password Reset

Method	Endpoint	Description	Auth
POST	`/api/v1/auth/admin/request-password-reset`	Initiate administrative password recovery with an expiring verification challenge.	🔒 Required
POST	`/api/v1/auth/admin/verify-reset-otp`	Verify one-time passcode challenge for password recovery workflow.	🔒 Required
POST	`/api/v1/auth/admin/reset-password`	Finalize administrative password reset with verified challenge token.	🔒 Required

POST /request-password-reset — Request & ResponseJSON

// Request
{
  "email": "admin@example.com",
  "tenantId": "optional-tenant-uuid",
  "method": "otp" // "otp" or "magic-link"
}

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

Profile Management

Method	Endpoint	Description	Auth
GET	`/api/v1/Admins/me`	Get the full profile of the currently authenticated admin, including role, permissions, and tenant info.	🔒 Required
PUT	`/api/v1/Admins/me`	Update the current admin's name and phone number.	🔒 Required
POST	`/api/v1/Admins/{id}/change-password`	Change password. Requires current password for verification.	🔒 Required
POST	`/api/v1/Admins/me/avatar`	Upload a new avatar image (max 2 MB, jpg/png/webp).	🔒 Required
DELETE	`/api/v1/Admins/me/avatar`	Remove the current avatar and revert to the default.	🔒 Required

GET /api/v1/Admins/me — ResponseJSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "admin@example.com",
  "username": "admin",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+1234567890",
  "avatarUrl": "/uploads/avatars/admin.png",
  "isActive": true,
  "twoFactorEnabled": true,
  "roleId": "superadmin-role-uuid",
  "roleName": "SuperAdmin",
  "tenantId": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "createdAt": "2026-01-01T00:00:00Z"
}

Security Endpoints

Method	Endpoint	Description	Auth
GET	`/api/v1/auth/admin/security-log`	View the admin's recent security events (logins, password changes, 2FA changes).	🔒 Required

PreviousAPI Reference NextUser Authentication API