Authentication API

Learn how to authenticate with the Menon Mobility API using JWT tokens and API keys.

Authentication Methods

Method	Use Case	Best For
JWT Token	User-authenticated requests	Web/mobile apps
API Key	Server-to-server integrations	Backend services

Endpoints Overview

Method	Endpoint	Description	Auth Required
POST	`/api/auth/register`	Register new user	No
POST	`/api/auth/login`	Login and get tokens	No
POST	`/api/auth/logout`	Invalidate session	Yes
POST	`/api/auth/refresh`	Refresh access token	No
GET	`/api/auth/me`	Get current user profile	Yes
PUT	`/api/auth/me`	Update user profile	Yes
POST	`/api/auth/verify-email`	Verify email address	No
POST	`/api/auth/resend-verification`	Resend verification code	No
POST	`/api/auth/forgot-password`	Request password reset	No
POST	`/api/auth/reset-password`	Reset password with token	No
POST	`/api/auth/change-password`	Change password (logged in)	Yes

Register User

Create a new user account.

Request

http

POST /api/auth/register
Content-Type: application/json

Body

json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "name": "John Smith",
  "role": "BUYER",
  "phone": "+1234567890",
  "companyName": "ABC Company",
  "country": "DE"
}

Body Parameters

Field	Type	Required	Description
`email`	string	Yes	Valid email address
`password`	string	Yes	Min 8 chars, 1 uppercase, 1 number
`name`	string	Yes	Full name (2-100 chars)
`role`	string	Yes	`BUYER` or `SELLER`
`phone`	string	No	Phone with country code
`companyName`	string	No	Required for sellers
`country`	string	No	ISO country code

Response (201 Created)

json

{
  "success": true,
  "data": {
    "user": {
      "id": "clx1234567890",
      "email": "user@example.com",
      "name": "John Smith",
      "role": "BUYER",
      "emailVerified": false
    },
    "message": "Registration successful. Please verify your email."
  }
}

Seller Registration with Documents

For seller registration with business documents:

http

POST /api/auth/register
Content-Type: multipart/form-data

email: seller@company.com
password: SecurePassword123!
name: Company Name
role: SELLER
companyName: ABC Trucks GmbH
documents[]: [file1.pdf]
documents[]: [file2.pdf]

Authenticate and receive JWT tokens.

Request

http

POST /api/auth/login
Content-Type: application/json

Body

json

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

Response (200 OK)

json

{
  "success": true,
  "data": {
    "user": {
      "id": "clx1234567890",
      "email": "user@example.com",
      "name": "John Smith",
      "role": "BUYER",
      "emailVerified": true,
      "avatar": "https://cdn.menonmobility.com/avatars/user.jpg"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}

Error Response (401 Unauthorized)

json

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}

Using the Access Token

Include the token in the Authorization header for authenticated requests:

bash

curl -X GET "https://api.menonmobility.com/api/auth/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Logout

Invalidate the current session.

Request

http

POST /api/auth/logout
Authorization: Bearer <access_token>

Response (200 OK)

json

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

Refresh Token

Get a new access token using the refresh token.

Request

http

POST /api/auth/refresh
Content-Type: application/json

Body

json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK)

json

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}

Token Expiration

Token Type	Expiration
Access Token	1 hour
Refresh Token	30 days

Get Current User

Retrieve the authenticated user's profile.

Request

http

GET /api/auth/me
Authorization: Bearer <access_token>

Response (200 OK)

json

{
  "success": true,
  "data": {
    "id": "clx1234567890",
    "email": "user@example.com",
    "name": "John Smith",
    "role": "SELLER",
    "phone": "+1234567890",
    "avatar": "https://cdn.menonmobility.com/avatars/user.jpg",
    "emailVerified": true,
    "phoneVerified": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "seller": {
      "id": "sel_abc123",
      "companyName": "ABC Trucks GmbH",
      "slug": "abc-trucks-gmbh",
      "verified": true,
      "trustScore": 92,
      "subscription": {
        "plan": "professional",
        "status": "active"
      }
    }
  }
}

Update Profile

Update the authenticated user's profile.

Request

http

PUT /api/auth/me
Authorization: Bearer <access_token>
Content-Type: application/json

Body

json

{
  "name": "John Smith Jr.",
  "phone": "+1987654321",
  "language": "de",
  "currency": "EUR"
}

Response (200 OK)

json

{
  "success": true,
  "data": {
    "id": "clx1234567890",
    "name": "John Smith Jr.",
    "phone": "+1987654321",
    "updatedAt": "2024-01-16T14:20:00Z"
  }
}

Verify Email

Verify email address with the code sent to user's email.

Request

http

POST /api/auth/verify-email
Content-Type: application/json

Body

json

{
  "email": "user@example.com",
  "code": "123456"
}

Response (200 OK)

json

{
  "success": true,
  "message": "Email verified successfully"
}

Resend Verification

Request a new verification code.

Request

http

POST /api/auth/resend-verification
Content-Type: application/json

Body

json

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

Response (200 OK)

json

{
  "success": true,
  "message": "Verification code sent"
}

Forgot Password

Request a password reset link.

Request

http

POST /api/auth/forgot-password
Content-Type: application/json

Body

json

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

Response (200 OK)

json

{
  "success": true,
  "message": "Password reset instructions sent to your email"
}

Reset Password

Reset password using the token from email.

Request

http

POST /api/auth/reset-password
Content-Type: application/json

Body

json

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

Response (200 OK)

json

{
  "success": true,
  "message": "Password reset successfully"
}

Change Password

Change password while logged in.

Request

http

POST /api/auth/change-password
Authorization: Bearer <access_token>
Content-Type: application/json

Body

json

{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewSecurePassword123!",
  "confirmPassword": "NewSecurePassword123!"
}

Response (200 OK)

json

{
  "success": true,
  "message": "Password changed successfully"
}

API Key Authentication

For server-to-server integrations, use API keys.

Generating API Keys

Go to Dashboard > Settings > API
Click "Generate API Key"
Name your key (e.g., "Production", "Development")
Copy the key immediately (shown once only)

Using API Keys

Include the key in the X-API-Key header:

bash

curl -X GET "https://api.menonmobility.com/api/v1/listings" \
  -H "X-API-Key: YOUR_API_KEY"

API Key Scopes

When creating a key, select permissions:

Scope	Access
`listings:read`	Read listings
`listings:write`	Create/update listings
`listings:delete`	Delete listings
`messages:read`	Read messages
`messages:write`	Send messages
`analytics:read`	Read analytics
`webhooks:manage`	Configure webhooks

Managing Keys

View and manage keys in Settings > API:

View active keys
See last used timestamp
Revoke compromised keys
Regenerate keys

Security Best Practices

API Key Security

Keep Keys Secret

Never expose API keys in client-side code or public repositories.

Do:

Store keys in environment variables
Use server-side requests only
Rotate keys periodically
Use minimal required scopes

Don't:

Commit keys to version control
Share keys in plain text
Use same key for dev and production

Request Signing

For additional security, sign requests:

bash

X-Signature: sha256=HMAC_SIGNATURE
X-Timestamp: 1642248000

Signature generated from:

Request body
Timestamp
Your API secret

IP Whitelisting

Restrict API access by IP:

Go to Settings > API > Security
Add allowed IP addresses
Enable IP restriction

Error Handling

Authentication Errors

Error Code	Description
`INVALID_API_KEY`	API key is invalid or revoked
`EXPIRED_TOKEN`	JWT token has expired
`INSUFFICIENT_SCOPE`	Token lacks required permissions
`INVALID_SIGNATURE`	Request signature is invalid

Example Error Response

json

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}

Testing Authentication

Verify Your Key

bash

GET /v1/auth/verify
Authorization: Bearer YOUR_API_KEY

Response:

json

{
  "success": true,
  "data": {
    "valid": true,
    "scopes": ["listings:read", "listings:write"],
    "expires_at": null
  }
}

Sandbox Keys

Use sandbox environment for testing:

Sandbox URL: https://sandbox-api.menonmobility.com/v1
Generate sandbox keys separately
No real data affected

Code Examples

Node.js

javascript

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.menonmobility.com/v1',
  headers: {
    'Authorization': `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Make requests
const listings = await api.get('/listings');

Python

python

import requests

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.menonmobility.com/v1/listings',
    headers=headers
)

PHP

php

<?php
$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.menonmobility.com/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . $apiKey,
        'Content-Type' => 'application/json'
    ]
]);

$response = $client->get('listings');

Authentication API ​

Authentication Methods ​

Endpoints Overview ​

Register User ​

Request ​

Body ​

Body Parameters ​

Response (201 Created) ​

Seller Registration with Documents ​

Login ​

Request ​

Body ​

Response (200 OK) ​

Error Response (401 Unauthorized) ​

Using the Access Token ​

Logout ​

Request ​

Response (200 OK) ​

Refresh Token ​

Request ​

Body ​

Response (200 OK) ​

Token Expiration ​

Get Current User ​

Request ​

Response (200 OK) ​

Update Profile ​

Request ​

Body ​

Response (200 OK) ​

Verify Email ​

Request ​

Body ​

Response (200 OK) ​

Resend Verification ​

Request ​

Body ​

Response (200 OK) ​

Forgot Password ​

Request ​

Body ​

Response (200 OK) ​

Reset Password ​

Request ​

Body ​

Response (200 OK) ​

Change Password ​

Request ​

Body ​

Response (200 OK) ​

API Key Authentication ​

Generating API Keys ​

Using API Keys ​

API Key Scopes ​

Managing Keys ​

Security Best Practices ​

API Key Security ​

Request Signing ​

IP Whitelisting ​

Error Handling ​

Authentication Errors ​

Example Error Response ​

Testing Authentication ​

Verify Your Key ​

Sandbox Keys ​

Code Examples ​

Node.js ​

Python ​

PHP ​

Related Topics ​

Authentication API

Authentication Methods

Endpoints Overview

Register User

Request

Body

Body Parameters

Response (201 Created)

Seller Registration with Documents

Login

Request

Body

Response (200 OK)

Error Response (401 Unauthorized)

Using the Access Token

Logout

Request

Response (200 OK)

Refresh Token

Request

Body

Response (200 OK)

Token Expiration

Get Current User

Request

Response (200 OK)

Update Profile

Request

Body

Response (200 OK)

Verify Email

Request

Body

Response (200 OK)

Resend Verification

Request

Body

Response (200 OK)

Forgot Password

Request

Body

Response (200 OK)

Reset Password

Request

Body

Response (200 OK)

Change Password

Request

Body

Response (200 OK)

API Key Authentication

Generating API Keys

Using API Keys

API Key Scopes

Managing Keys

Security Best Practices

API Key Security

Request Signing

IP Whitelisting

Error Handling

Authentication Errors

Example Error Response

Testing Authentication

Verify Your Key

Sandbox Keys

Code Examples

Node.js

Python

PHP

Related Topics