API Authentication

All API requests require authentication. Bleemeo supports two authentication methods:

Method	Best For
Basic Authentication	Quick testing, browser exploration
JSON Web Tokens (JWT)	Production applications, automated scripts

Basic Authentication

Use HTTP Basic Authentication with your Bleemeo username and password.

When you browse to api.bleemeo.com/v1/ in your browser, you’ll be prompted for credentials automatically.

Example with curl:

curl -u "your-email@example.com:your-password" \
  https://api.bleemeo.com/v1/agent/

Note

Basic authentication sends credentials with every request. For production use, we recommend JWT authentication.

JWT Authentication

JSON Web Tokens provide a more secure authentication flow for applications:

1. Exchange credentials for a token pair (access + refresh)
2. Use the access token for API requests
3. Refresh the token before it expires

Step 1: Get Your Tokens

POST /v1/jwt-auth/

Exchange credentials for JWT tokens

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

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Save both tokens:

• token — Access token for API requests (valid for 5 minutes)
• refresh — Refresh token for getting new access tokens (valid for 7 days)

Step 2: Make Authenticated Requests

Include the access token in the Authorization header:

curl -H "Accept: application/json" \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.bleemeo.com/v1/agent/

Step 3: Refresh Your Token

Before your access token expires, get a new one using the refresh token:

POST /v1/jwt-refresh/

Get a new access token

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
  https://api.bleemeo.com/v1/jwt-refresh/

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

You can refresh tokens multiple times until the refresh token expires (7 days). After that, you’ll need to re-authenticate with your credentials.

Token Expiration Summary

Token	Validity	Renewal
Access token	5 minutes	Use refresh endpoint
Refresh token	7 days	Re-authenticate with credentials

Best Practices

• Never hardcode credentials in your application code
• Store tokens securely and never expose them in logs or version control
• Implement token refresh logic to handle expiration gracefully
• Use environment variables for credentials in scripts and CI/CD pipelines