Authentication API - Steer Autos Documentation

Overview

The Authentication API handles user registration, login, session management, email verification, and password reset flows. All authentication uses secure HTTP-only cookies for session management with JWT tokens.

Authentication Flow

Endpoints

Register New User

POST

endpoint

/auth/register

Create a new user account. An email verification link will be sent to the provided email address. Request Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "password": "SecurePassword123!"
}

string

required

Valid email address

name

string

required

Full name (minimum 2 characters)

password

string

required

Strong password (minimum 8 characters)

Response:

{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "emailVerified": false,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}

Users must verify their email before they can fully access the platform.

POST

endpoint

/auth/login

Authenticate a user and establish a session. Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

string

required

User’s email address

password

string

required

User’s password

Response:

{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true
  }
}

Cookies Set:

accessToken - HTTP-only, Secure, SameSite=Strict (15 minutes)
refreshToken - HTTP-only, Secure, SameSite=Strict (7 days)

Get Current User

GET

endpoint

/auth/me

Retrieve the currently authenticated user’s information. Headers:

Cookie: accessToken=...

Response:

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER",
    "emailVerified": true,
    "createdAt": "2024-01-17T10:30:00Z"
  }
}

Refresh Access Token

POST

endpoint

/auth/refresh

Obtain a new access token using the refresh token. Headers:

Cookie: refreshToken=...

Response:

{
  "ok": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "USER"
  }
}

Cookies Updated:

New accessToken issued
refreshToken rotated for security

Logout

POST

endpoint

/auth/logout

Terminate the user’s session and invalidate tokens. Headers:

Cookie: accessToken=...

Response:

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

Cookies Cleared:

accessToken removed
refreshToken removed

Verify Email

POST

endpoint

/auth/verify-email

Verify a user’s email address using the verification token sent via email. Request Body:

{
  "token": "verification_token_from_email"
}

token

string

required

Email verification token

Response:

{
  "success": true,
  "message": "Email verified successfully. You can now log in."
}

Resend Verification Email

POST

endpoint

/auth/send-email-verification

Request a new verification email if the previous one expired or was lost. Request Body:

{
  "email": "user@example.com"
}

string

required

User’s email address

Response:

{
  "success": true,
  "message": "Verification email sent. Please check your inbox."
}

Rate Limit: This endpoint is rate-limited to prevent abuse:

5 requests per hour per email address

Forgot Password

POST

endpoint

/auth/forgot-password

Request a password reset link via email. Request Body:

{
  "email": "user@example.com"
}

string

required

User’s email address

Response:

{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}

For security, the API always returns a success message regardless of whether the email exists.

Reset Password

POST

endpoint

/auth/reset-password

Reset password using the token received via email. Request Body:

{
  "token": "reset_token_from_email",
  "password": "NewSecurePassword123!"
}

token

string

required

Password reset token from email

password

string

required

New password (minimum 8 characters)

Response:

{
  "success": true,
  "message": "Password reset successful. You can now log in with your new password."
}

Security Features

HTTP-Only Cookies

All session tokens are stored in HTTP-only cookies to prevent XSS attacks. JavaScript cannot access these cookies.

Secure Flag

Cookies are marked as Secure, ensuring they’re only transmitted over HTTPS in production.

SameSite Policy

Cookies use SameSite=Strict to prevent CSRF attacks.

Token Rotation

Refresh tokens are rotated on each use to minimize security risks if a token is compromised.

Password Requirements

Minimum 8 characters
Recommended: Mix of uppercase, lowercase, numbers, and special characters

Token Expiration

Access Token: 15 minutes
Refresh Token: 7 days
Verification Token: 24 hours
Reset Token: 1 hour

Error Codes

Code	Status	Description
`INVALID_CREDENTIALS`	401	Incorrect email or password
`EMAIL_ALREADY_EXISTS`	409	Email is already registered
`EMAIL_NOT_VERIFIED`	403	Email verification required
`INVALID_TOKEN`	400	Token is invalid or expired
`TOKEN_EXPIRED`	401	Token has expired
`WEAK_PASSWORD`	400	Password doesn’t meet requirements
`RATE_LIMIT_EXCEEDED`	429	Too many requests

Use Cases

Example 1: Complete Registration Flow

# Step 1: Register
curl -X POST "https://api.steerai.autos/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com",
    "name": "Auto Dealer",
    "password": "SecurePass123!"
  }'

# Step 2: User receives email and verifies
curl -X POST "https://api.steerai.autos/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verification_token_from_email"
  }'

# Step 3: Login
curl -X POST "https://api.steerai.autos/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "dealer@example.com",
    "password": "SecurePass123!"
  }'

Example 2: Password Reset Flow

# Step 1: Request reset
curl -X POST "https://api.steerai.autos/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dealer@example.com"
  }'

# Step 2: Reset with token from email
curl -X POST "https://api.steerai.autos/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset_token_from_email",
    "password": "NewSecurePass123!"
  }'

Example 3: Token Refresh

# Refresh access token before it expires
curl -X POST "https://api.steerai.autos/v1/auth/refresh" \
  -b cookies.txt \
  -c cookies.txt

Client Implementation

JavaScript/Node.js

class AuthClient {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  async register(email, name, password) {
    const response = await fetch(`${this.baseURL}/auth/register`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, name, password })
    });
    return response.json();
  }

  async login(email, password) {
    const response = await fetch(`${this.baseURL}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include', // Important for cookies
      body: JSON.stringify({ email, password })
    });
    return response.json();
  }

  async getCurrentUser() {
    const response = await fetch(`${this.baseURL}/auth/me`, {
      credentials: 'include'
    });
    return response.json();
  }

  async logout() {
    const response = await fetch(`${this.baseURL}/auth/logout`, {
      method: 'POST',
      credentials: 'include'
    });
    return response.json();
  }
}

Best Practices

Always use HTTPS in production

Never transmit credentials over unsecured HTTP connections.

Implement client-side token refresh

Automatically refresh tokens before they expire to maintain session continuity.

Store refresh tokens securely

Use HTTP-only cookies (handled automatically by our API) rather than localStorage.

Enforce strong password policies

Require passwords with adequate complexity and length.

Implement rate limiting

Protect authentication endpoints from brute-force attacks.

Log authentication events

Track login attempts, password resets, and suspicious activity.

Getting Started

Quick start guide for authentication

Security Guide

Comprehensive security best practices

Users API

User management and profile endpoints

Teams API

Team collaboration and permissions

API Documentation

​Overview

​Authentication Flow

​Endpoints

​Register New User

​Login

​Get Current User

​Refresh Access Token

​Logout

​Verify Email

​Resend Verification Email

​Forgot Password

​Reset Password

​Security Features

​HTTP-Only Cookies

​Secure Flag

​SameSite Policy

​Token Rotation

​Password Requirements

​Token Expiration

​Error Codes

​Use Cases

​Example 1: Complete Registration Flow

​Example 2: Password Reset Flow

​Example 3: Token Refresh

​Client Implementation

​JavaScript/Node.js

​Best Practices

​Related Resources

Getting Started

Security Guide

Users API

Teams API

Overview

Authentication Flow

Endpoints

Register New User

Login

Get Current User

Refresh Access Token

Logout

Verify Email

Resend Verification Email

Forgot Password

Reset Password

Security Features

HTTP-Only Cookies

Secure Flag

SameSite Policy

Token Rotation

Password Requirements

Token Expiration

Error Codes

Use Cases

Example 1: Complete Registration Flow

Example 2: Password Reset Flow

Example 3: Token Refresh

Client Implementation

JavaScript/Node.js

Best Practices

Related Resources