API Authentication

All API requests require authentication. The Bleemeo API uses standard OAuth 2.0 tokens, and also accepts Basic authentication for quick tests.

Caution

Authentication with a username and password is refused for a user with two-factor authentication enabled. To call the API from scripts, use a dedicated user without 2FA, with only the roles the script needs.

Recommended: Official SDKs

The easiest way to use the API is through our official Python and Go SDKs. They handle authentication for you: they obtain an OAuth token from your credentials, renew it when it expires, and revoke it when you are done. They also take care of pagination, errors and retries.

Python

python -m pip install --upgrade bleemeo

from bleemeo import Client, Resource

with Client(load_from_env=True) as client:
    page = client.get_page(Resource.AGENT, page=1, page_size=10)
    for agent in page.json()["results"]:
        print(agent["display_name"])

BLEEMEO_USER=your-email@example.com BLEEMEO_PASSWORD=your-password python3 list_agents.py

Go

go get -u github.com/bleemeo/bleemeo-go

client, err := bleemeo.NewClient(bleemeo.WithConfigurationFromEnv())
if err != nil {
  log.Fatalln("Failed to initialize client:", err)
}

defer client.Logout(context.Background())

page, err := client.GetPage(context.Background(), bleemeo.ResourceAgent, 1, 10, url.Values{})

BLEEMEO_USER=your-email@example.com BLEEMEO_PASSWORD=your-password go run list-agents.go

See each SDK’s README for all configuration options and more examples.

OAuth 2.0 Without an SDK

The SDKs use the standard OAuth 2.0 flow, with no Bleemeo-specific step. If you work in another language, any OAuth 2.0 client library works, or you can make the HTTP calls yourself as shown below.

All requests use the public client ID 29a6c65e-8c9d-4c6e-b478-1c7ea99c34f2, with no client secret.

Step 1: Get a Token

Exchange your credentials for a token, using the password grant:

POST/o/token/

Exchange credentials for an access token and a refresh token

curl -X POST \
  -d grant_type=password \
  -d client_id=29a6c65e-8c9d-4c6e-b478-1c7ea99c34f2 \
  --data-urlencode "username=your-email@example.com" \
  --data-urlencode "password=your-password" \
  https://api.bleemeo.com/o/token/

Response:

{
  "access_token": "9Fk2...",
  "expires_in": 36000,
  "token_type": "Bearer",
  "refresh_token": "Xa7p..."
}

• access_token — Token to send with your API requests
• expires_in — Number of seconds the access token remains valid. The lifetime may change, so always rely on this field rather than a fixed duration
• refresh_token — Token to get a new access token without sending your credentials again

Step 2: Make Authenticated Requests

Send the access token in the Authorization header:

curl -H "Authorization: Bearer 9Fk2..." \
  https://api.bleemeo.com/v1/agent/

Step 3: Refresh the Token

When the access token expires, or when the API answers with a 401 status, get a new one with the refresh_token grant:

POST/o/token/

Get a new access token from a refresh token

curl -X POST \
  -d grant_type=refresh_token \
  -d client_id=29a6c65e-8c9d-4c6e-b478-1c7ea99c34f2 \
  -d refresh_token=Xa7p... \
  https://api.bleemeo.com/o/token/

The response has the same format as in step 1. It contains a new refresh token: keep it for the next refresh, as the previous one is no longer valid. If the refresh fails, authenticate again with your credentials.

Step 4: Revoke the Token

When your script is done, revoke the refresh token. This also revokes the related access token:

POST/o/revoke_token/

Revoke a token so it can no longer be used

curl -X POST \
  -d client_id=29a6c65e-8c9d-4c6e-b478-1c7ea99c34f2 \
  -d token_type_hint=refresh_token \
  -d token=Xa7p... \
  https://api.bleemeo.com/o/revoke_token/

Basic Authentication

For a quick test from the command line, you can also use HTTP Basic Authentication with your Bleemeo username and password:

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

For scripts and integrations, use an official SDK or OAuth 2.0 tokens instead.

Best Practices

• Never hardcode credentials in your application code
• Use environment variables for credentials in scripts and CI/CD pipelines
• Keep tokens secret and never expose them in logs or version control
• Revoke your token when your script is done