Authentication

Fleet Orchestrator uses token-based authentication. This guide covers login flows, token management, and best practices.

Authentication Flow

1. Login with credentials → Get access token + refresh token
2. Use access token for API requests
3. When access token expires → Use refresh token to get new access token
4. When refresh token expires → Login again

Obtain tokens by authenticating with your credentials:

curl -X POST https://api.moovex.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600,
  "user": {
    "_id": "user_123",
    "email": "your-email@example.com",
    "role": "admin",
    "companyRef": "company_456",
    "siteRef": "site_789"
  }
}

Field	Description
`accessToken`	JWT token for API requests (short-lived)
`refreshToken`	Token to obtain new access tokens (long-lived)
`expiresIn`	Access token lifetime in seconds
`user`	Authenticated user details

Using Access Tokens

Include the access token in the Authorization header:

curl https://api.moovex.ai/api/v1/reservations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Refresh

When the access token expires, use the refresh token to obtain a new one:

curl -X POST https://api.moovex.ai/api/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}

Token Expiration

Token	Lifetime	Action When Expired
Access Token	1 hour	Refresh using refresh token
Refresh Token	7 days	Login again

For server-to-server integrations, you can use auto-login with a long-lived API key:

curl -X POST https://api.moovex.ai/api/v1/auth/auto-login \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your-api-key"
  }'

Contact support to obtain an API key for your account.

Who Am I

Verify your current authentication and get user details:

curl https://api.moovex.ai/api/v1/auth/whoami \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "user": {
    "_id": "user_123",
    "email": "your-email@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "admin",
    "permissions": ["read", "write", "admin"]
  },
  "company": {
    "_id": "company_456",
    "name": "Acme Transportation"
  },
  "site": {
    "_id": "site_789",
    "name": "NYC Operations"
  }
}

User Roles

Role	Description
`admin`	Full access to all resources and settings
`dispatcher`	Manage reservations, trips, and drivers
`viewer`	Read-only access
`driver`	Access to assigned trips only (driver app)

Error Responses

Invalid Credentials

{
  "statusCode": 401,
  "message": "Invalid email or password"
}

Token Expired

{
  "statusCode": 401,
  "message": "Token expired",
  "code": "TOKEN_EXPIRED"
}

Invalid Token

{
  "statusCode": 401,
  "message": "Invalid token",
  "code": "INVALID_TOKEN"
}

Best Practices

Store tokens securely - Never expose tokens in client-side code or logs
Implement token refresh - Proactively refresh tokens before expiration
Handle 401 errors - Automatically refresh and retry when receiving 401
Use API keys for servers - For backend integrations, use long-lived API keys
Scope appropriately - Create users with minimum required permissions

Two-Factor Authentication

If 2FA is enabled for your account, the login flow requires an additional step:

curl -X POST https://api.moovex.ai/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Response (2FA Required)

{
  "requires2FA": true,
  "tempToken": "temp_abc123"
}

Step 2: Verify OTP

curl -X POST https://api.moovex.ai/api/v1/auth/otp/check \
  -H "Content-Type: application/json" \
  -d '{
    "tempToken": "temp_abc123",
    "otp": "123456"
  }'

This returns the standard login response with access and refresh tokens.

Authentication

On this page