osmedeus/docs/api/authentication.md

Authentication

Most API endpoints require JWT authentication. First, obtain a token via the login endpoint, then include it in subsequent requests.

Login

POST /osm/api/login

Authenticate and obtain a JWT token.

Request

curl -X POST http://localhost:8002/osm/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "osmedeus",
    "password": "your-password"
  }'

Request Body

Field	Type	Required	Description
username	string	Yes	Username configured in server settings
password	string	Yes	Password for the user

Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6Im9zbWVkZXVzIiwiZXhwIjoxNzA0MDY3MjAwLCJpYXQiOjE3MDQwNjM2MDB9.abc123..."
}

Error Responses

400 Bad Request - Invalid request body:

{
  "error": true,
  "message": "Invalid request body"
}

401 Unauthorized - Invalid credentials:

{
  "error": true,
  "message": "Invalid credentials"
}

Token Details

• Algorithm: HS256 (HMAC-SHA256)
• Expiration: Configurable via server.jwt.expiration_minutes in settings (default: 60 minutes)
• Claims: Contains username, exp (expiration), and iat (issued at)

Using the Token

Include the token in subsequent requests using the Authorization: Bearer <token> header:

# Store token in environment variable
export TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Use in API requests
curl http://localhost:8002/osm/api/workflows \
  -H "Authorization: Bearer $TOKEN"

Authentication Errors

401 Unauthorized - Missing header:

{
  "error": true,
  "message": "Missing authorization header"
}

401 Unauthorized - Invalid format:

{
  "error": true,
  "message": "Invalid authorization header format"
}

401 Unauthorized - Expired or invalid token:

{
  "error": true,
  "message": "Invalid or expired token"
}

Disabling Authentication

Authentication can be disabled by starting the server with the --no-auth flag:

osmedeus server --no-auth

When disabled, all API endpoints are accessible without a token.