Skip to content

Authentication

The Madevo API uses JWT-based authentication for all secure endpoints.

Overview

Authentication works as follows:

  1. Login to obtain a JWT token
  2. Include the token in all secure requests
  3. Refresh the token when it expires
  4. Logout to revoke the session

Login

Endpoint

POST /api/v1/login

Request

Headers

Content-Type: application/json

Body

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

Response

{
  "error": false,
  "message": "login successful",
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "company_id": "string",
    "role": "string",
    "is_active": true,
    "meta": {},
    "created_at": "string"
  },
  "token": "<jwt>"
}

Notes

  • The token is required for all secure endpoints
  • Login fails if credentials are invalid or account is inactive

Example

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

Using the token

All secure endpoints require:

Authorization: Bearer <jwt>

Example

curl https://api.example.com/api/v1/secure/currentuser \
  -H 'Authorization: Bearer <jwt>'

Token lifecycle

  • Access token lifetime: 15 minutes
  • Session lifetime: 7 days

If the token is invalid:

{
  "error": true,
  "message": "unauthorized - invalid token"
}

Refresh token

Endpoint

POST /api/v1/refresh-token

Request

Headers

Authorization: Bearer <expired-jwt>
Content-Type: application/json

Body

{
  "token": "<expired-jwt>"
}

Response

{
  "error": false,
  "message": "token refreshed",
  "user": {
    "id": "string",
    "email": "string"
  },
  "token": "<new-jwt>"
}

Notes

  • Token must be provided in both header and body
  • Session must still be valid

Logout

Endpoint

POST /api/v1/secure/logout

Request

Authorization: Bearer <jwt>

Response

{
  "error": false,
  "message": "logged out"
}

WebSocket authentication

Use the token as a query parameter:

wss://api.example.com/api/v1/stream/:room_id?token=<jwt>

Best practices

  • Store tokens securely
  • Refresh tokens before expiry
  • Do not expose tokens in logs
  • Handle authentication errors gracefully