Login & Registration

Endpoints for user authentication and account creation.

Register

Create a new user account.

POST /api/v1/auth/register

Request

curl -X POST https://your-instance.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Request Body

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`password`	string	Yes	Password meeting requirements

Password Requirements

Minimum 8 characters
Maximum 128 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

Response

Success (201):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Errors

Status	Error	Cause
400	`Email and password are required`	Missing fields
400	`Invalid email format`	Email validation failed
400	`Password does not meet requirements`	Weak password
400	`Unable to create account`	Email already exists

The "Unable to create account" error is intentionally generic to prevent email enumeration attacks.

Login

Authenticate an existing user.

POST /api/v1/auth/login

Request

curl -X POST https://your-instance.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "rememberMe": false
  }'

Request Body

Field	Type	Required	Description
`email`	string	Yes	User's email address
`password`	string	Yes	User's password
`rememberMe`	boolean	No	Extended refresh token (30 days vs 24h)

Response

Success (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Errors

Status	Error	Cause
400	`Email and password are required`	Missing fields
401	`Invalid email or password`	Wrong credentials
423	`Account is temporarily locked...`	Too many failed attempts

Account Lockout

After 5 failed login attempts, the account is locked for 15 minutes.

Lockout Response (423):

{
  "error": "Account is temporarily locked due to too many failed login attempts",
  "lockedUntil": "2024-01-15T10:45:00.000Z"
}

The lockout:

Resets automatically after 15 minutes
Resets on successful login
Counter resets after successful login

Get Current User

Get information about the authenticated user.

GET /api/v1/auth/me

Request

curl -X GET https://your-instance.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

Success (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Errors

Status	Error	Cause
401	`Authorization header required`	No token
401	`Invalid token`	Token invalid or expired

Logout

Logout the current user and invalidate tokens.

POST /api/v1/auth/logout

Request

curl -X POST https://your-instance.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

Request Body (Optional)

Field	Type	Required	Description
`refreshToken`	string	No	Refresh token to explicitly revoke

Response

Success (200):

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

What Happens on Logout

Access token blacklisted - Immediately invalidated via Redis
Refresh token revoked - If provided, removed from Redis
Client should - Clear stored tokens

The access token is blacklisted for its remaining lifetime (up to 15 minutes), ensuring it cannot be reused.

Authentication Flow Example

1. Register or Login

// Login
const response = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecurePassword123!',
    rememberMe: true
  })
});
 
const { accessToken, refreshToken, user } = await response.json();
 
// Store tokens securely
storeAccessToken(accessToken);
storeRefreshToken(refreshToken);

2. Make Authenticated Requests

const response = await fetch('/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${getAccessToken()}`
  }
});

3. Handle Token Expiration

// When access token expires (401 response)
const refreshResponse = await fetch('/api/v1/auth/refresh', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    refreshToken: getRefreshToken()
  })
});
 
if (refreshResponse.ok) {
  const { accessToken, refreshToken } = await refreshResponse.json();
  storeAccessToken(accessToken);
  storeRefreshToken(refreshToken);
  // Retry original request
} else {
  // Redirect to login
  redirectToLogin();
}

4. Logout

await fetch('/api/v1/auth/logout', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${getAccessToken()}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refreshToken: getRefreshToken()
  })
});
 
// Clear stored tokens
clearTokens();

API Keys Token Refresh