Introduction#
The NudgeScribe Backend Core API is a comprehensive system for managing users, authentication, permissions, and workspaces in an enterprise environment. The system implements:Role-Based Access Control (RBAC) with account and workspace-level permissions
Multi-Factor Authentication (MFA) using TOTP
JWT-based session management with geographic verification
Comprehensive audit logging for compliance
Enterprise-grade security with encrypted payloads and secure password handling
API Versioning#
All endpoints are versioned under /v1/ and follow RESTful conventions.
Authentication#
Authentication & API Keys#
In order for you to be able to access the Developer environment of Nudgescribe, you will need an API Key.1. Sign Up#
Nudgescribe integrations use either an API Key or an Access Token to authenticate API calls:An API Key is used for Authentication purposes.
An Access Token is used for all API calls that require an authenticated user.
To call Nudgescribe APIs, you'll exchange your API Key for an Access Token. Keep this Key and Token safe.
1.
Be a registered user: You can sign up to Nudgscribe with your work email address and a unique password.
2.
Have the Developer Role: You need to have the developer role assigned to your user to gain access to your API Key.
2. Get Your API Key#
Once you have successfully signed in, you simply navigate to the User Role screen and assign the Developer role to yourself. If this screen is not available to you, reach out to your account owner to request the Developer role.You can then click on your User Profile icon and click on the Get API Key button, which will copy your unique API Key to the clipboard.Do Not Share Your API Key! Anyone with your API Key can gain developer access and make changes on your behalf. Keep this secret.
Do Not Share API Keys! Rather, reach out to your account owner to request the Developer role or assign the Developer role to yourself if you have access to the User Role screen.
3. Get Access Token and Re-Auth Token#
Once you have your API Key, you are ready to Authenticate yourself as a developer and receive your Access Token for all subsequent API calls and a Re-Auth Token to refresh your expired Access Token.Simply use the Authenticate API to gain access to your Access Token and Refresh Token, and the Re-Authenticate API to refresh your expired Access Token.Authentication & Bearer Tokens#
All protected endpoints in this API require Bearer Token authentication. After a successful sign-in or password reset, you will receive an access token (JWT). This token must be included in the Authorization header of your API requests.How to Use#
Include the following header in your HTTP requests:
Authorization: Bearer <your-access-token>How It Works#
The access token proves your identity and permissions.
The backend validates the token on every request.
If the token is missing, expired, or invalid, you will receive a 401 Unauthorized error.
Security Notes#
Never share your access token.
Store tokens securely (e.g., in memory or secure storage, not in localStorage for browser apps).
Tokens expire after a set period (14 days); you must re-authenticate to get a new one.
Endpoints Table of Contents#
Getting Started: Authentication
Campaigns and Campaign Messages
Overall Security & Compliance#
Security Features#
Geographic Verification#
Tracks user sign-in locations using IP geolocation
Sends warning emails for sign-ins from new locations
Stores geographic snapshots for security monitoring
Password Security#
Passwords hashed using bcrypt with salt rounds
Plain text passwords are never stored
Secure password reset with time-limited codes
MFA Implementation#
TOTP-based using standard RFC 6238
Secrets encrypted at rest
Support for popular authenticator apps
Session Management#
Stateless JWT tokens with 14-day expiration
Role-based access control (RBAC) integration
Automatic token refresh not implemented (manual re-authentication required)
Database Context & Roles#
The system uses PostgreSQL row-level security with dynamic role switching:Admin Users: Use the postgres role with full access
Authenticated Users: Use the access_user role with row-level security
Anonymous Users: Limited to authentication endpoints only
Session variables set during authentication:#
app.user_id: Current user's ID
app.account_id: Current user's account ID
app.user_email: User's email (for auth endpoints)
Rate Limiting & Security#
Recommended Rate Limits#
Sign-in attempts: 5 per minute per IP
MFA verification: 3 per minute per user
Password reset requests: 1 per 15 minutes per email
Failed Attempt Tracking#
The system tracks failed attempts in the ChallengeAuth entity:failed_signin_attempts: Failed password attempts
failed_validation_attempts: Failed MFA attempts
Compliance & Audit#
Security Compliance#
Passwords are never logged or exposed in responses
MFA secrets are encrypted and excluded from serialisation
Geographic tracking for suspicious activity detection
Comprehensive audit trails for all authentication events
Data Privacy#
Sensitive fields marked with @Exclude() decorator
IP addresses stored for security monitoring
Email addresses used for communication and verification
Audit Trail Fields#
All authentication events tracked with:Timestamps for all actions
IP addresses and geographic locations
Attempt counters for failed operations
