Skip to main content

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

Request Body

Response (200 OK)

Error Responses

400 Bad Request - Invalid request body:
401 Unauthorized - Invalid credentials:

Logout

POST /osm/api/logout Clear the session cookie to log out.

Request

Response (200 OK)


Token Details

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

Using the Token

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

Authentication Errors

401 Unauthorized - Missing header:
401 Unauthorized - Invalid format:
401 Unauthorized - Expired or invalid token:

API Key Authentication

As an alternative to JWT tokens, you can authenticate using a static API key via the x-osm-api-key header. This is useful for scripts, CI/CD pipelines, or integrations where managing JWT token refresh is impractical.

Configuration

API key authentication is configured in ~/osmedeus-base/osm-settings.yaml:

Using the API Key

Include the API key in requests using the x-osm-api-key header:

Error Response

401 Unauthorized - Invalid or missing API key:

Notes

  • API key authentication takes priority over JWT when enabled
  • A random 32-character API key is automatically generated on first server start
  • The API key is stored in plain text in the settings file; ensure appropriate file permissions
  • Empty, whitespace-only, or placeholder values (null, undefined, nil) are rejected

Disabling Authentication

Authentication can be disabled by starting the server with the --no-auth flag:
When disabled, all API endpoints are accessible without a token.