Authentication

The NextRoute API uses JWT (JSON Web Token) authentication. All authenticated endpoints require a valid JWT in the Authorization header. Tokens are obtained through the signup or login endpoints.

Base URL

https://api.nextroute.app

Token Format

All authenticated requests must include the JWT token as a Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The JWT payload contains:

All data queries are automatically scoped to the user's tenantId, ensuring complete tenant isolation.

Signup

Create a new tenant account with an owner user.

curl -X POST https://api.nextroute.app/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "john@example.com",
    "password": "securepassword",
    "businessName": "Smith Bin Cleaning",
    "vertical": "bin-cleaning"
  }'

Request Body:

Response (201):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "john@example.com",
    "name": "John Smith",
    "role": "owner",
    "tenantId": "ten_xyz789",
    "tenantName": "Smith Bin Cleaning",
    "verticalSlug": "bin-cleaning"
  }
}

New accounts start on a 14-day Professional plan trial.

Error Responses:

Login

Authenticate an existing user and receive a JWT token.

curl -X POST https://api.nextroute.app/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "securepassword"
  }'

Request Body:

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "john@example.com",
    "name": "John Smith",
    "role": "owner",
    "tenantId": "ten_xyz789",
    "tenantName": "Smith Bin Cleaning",
    "verticalSlug": "bin-cleaning"
  }
}

Error Responses:

Forgot Password

Request a password reset email. Always returns a success response to prevent email enumeration.

curl -X POST https://api.nextroute.app/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com"}'

Response (200):

{
  "message": "If an account exists with that email, a reset link has been sent."
}

The reset email contains a link to https://nextroute.app/reset-password/{token}. The token:

• Expires after 1 hour
• Is invalidated when the password is changed (HMAC includes the password hash)
• Is a base64url-encoded string containing the user ID, expiry timestamp, and HMAC signature

Reset Password

Reset a user's password using a valid reset token.

curl -X POST https://api.nextroute.app/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "dXNyX2FiYzEyMzoxNzExMjM0NTY3OmFiY2RlZjEyMzQ1Ng",
    "password": "newSecurePassword"
  }'

Response (200):

{
  "message": "Password has been reset successfully"
}

Error Responses:

Rate Limiting

Authentication endpoints are rate-limited per IP address to prevent brute-force attacks:

When rate limited, the API returns a 429 status code with a descriptive error message.

Security Notes

• Passwords are securely hashed before storage
• JWTs are signed with an HMAC-SHA256 secret
• All data is scoped to the authenticated user's tenant
• Reset tokens are self-invalidating (tied to the current password hash)
• Email addresses are normalized to lowercase

Related

• API Customers — manage customers after authentication
• API Routes — manage routes after authentication
• API Billing — manage invoices and payments after authentication