Authentication¶

Who can do this: viewers, operators and organization administrators. Every Pulse user can request an API token; what the token can do depends on the role you hold in each organization.

The Pulse API is the same interface the web application uses. You call it over HTTPS with a bearer token that you obtain from your Pulse email address and password. There are no separate API keys.

Base URL¶

All paths in this chapter are relative to your Pulse address. The examples use https://pulse.labmonitors.com; replace it with the address you use to sign in.

Every endpoint lives under /api/v1/, for example https://pulse.labmonitors.com/api/v1/alarms. Always use https://.

Obtain a token¶

Send your email address and password as a URL-encoded form to the token endpoint.

Item	Value
Method and path	`POST /api/v1/auth/token`
Content type	`application/x-www-form-urlencoded`
Who can call it	anyone with an active Pulse account (no token needed)

Form fields:

Field	Required	Meaning
`username`	yes	Your Pulse email address. Letter case and surrounding spaces are ignored.
`password`	yes	Your Pulse password.

grant_type=password may be sent for compatibility with OAuth 2.0 password-grant clients but is not required.

Success response, 200 OK:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIs...",
  "token_type": "bearer"
}

Error responses:

Status	Body	When
`401`	`{"detail": "Incorrect email or password"}`	Wrong password, unknown email address, or an account that has not set a password yet. The response also carries `WWW-Authenticate: Bearer`.
`400`	`{"detail": "Inactive user"}`	The password is correct but the account has been deactivated.
`429`	`{"detail": "Too many attempts. Try again in 8s."}`	You are being throttled after repeated failures. The number of seconds varies; see Throttling.
`422`	`{"detail": [ ... ]}`	A required form field is missing. The body lists the missing fields.

Note

An account that has never completed activation has no password and cannot obtain a token. Complete activation or use Forgot password in the web application first.

curl example¶

TOKEN=$(curl -s -X POST https://pulse.labmonitors.com/api/v1/auth/token \
  -d "username=jane@example.org" \
  --data-urlencode "password=your-password" \
  | python -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

curl -s https://pulse.labmonitors.com/api/v1/alarms \
  -H "Authorization: Bearer $TOKEN"

--data-urlencode protects passwords that contain &, + or %.

Use the token¶

Send the token in the Authorization header of every request:

Authorization: Bearer <access_token>

Treat the token as an opaque string. Do not decode it or rely on its contents; the fields inside it may change.

What the token can do¶

A token carries your identity, not a fixed set of permissions. On every request Pulse looks up the roles you currently hold and applies them:

Viewer in an organization: read alarms and downtimes for that organization.
Operator: read, plus acknowledge and un-acknowledge alarms, mute and unmute services, and schedule or cancel downtimes.
Organization administrator: everything an operator can do, plus edit service alarm limits and notification settings.

If your role changes while a token is valid, the token immediately gains or loses those abilities. See Roles at a glance and the Permissions matrix.

Check a token¶

GET /api/v1/auth/me returns the account behind the token:

{
  "id": 42,
  "name": "Jane Doe",
  "email": "jane@example.org",
  "timezone": "America/Vancouver"
}

If the request carries no token at all, this endpoint still returns 200 with id, name and email set to null and "timezone": "UTC". An expired or revoked token returns 401 instead.

Token lifetime and revocation¶

A token is valid for 8 hours from the moment it is issued. There is no refresh call; request a new token when the old one expires.

A token stops working before it expires when any of the following happens:

Event	Effect
You change your password (yourself, through Forgot password, or an administrator sets it for you)	Every token issued before the change is rejected.
You log out of the web application (Logout, which calls `GET` or `POST /api/v1/auth/logout`)	Every token for your account is rejected, on every device and in every script.
Your account is deactivated	Every token is rejected on its next use.

Warning

Logging out of the web application also revokes the tokens your scripts are using. Request a fresh token after you log out.

To revoke your tokens from a script, call the logout endpoint with the token as a bearer header (or as the access_token cookie):

curl -s -o /dev/null -H "Authorization: Bearer $TOKEN" \
  https://pulse.labmonitors.com/api/v1/auth/logout

The logout endpoint always answers 302 Found with Location: /login. Tokens are revoked only when the token you present is still valid; calling logout with an expired, already-revoked or malformed token changes nothing for your other sessions. Pulse records both the token request and a logout made with a valid token in your organization's audit log.

Once revoked or expired, a token produces 401 {"detail": "Could not validate credentials"} on every endpoint that requires authentication.

401 and 403¶

Status	Meaning	Typical bodies
`401 Unauthorized`	Pulse does not know who you are. The token is missing, expired, revoked, or malformed. Request a new token.	`{"detail": "Authentication required"}` on the alarms and downtimes lists; `{"detail": "Could not validate credentials"}` when a token is present but invalid.
`403 Forbidden`	Pulse knows who you are, but your role does not allow the action, or the service is not in one of your organizations. A new token will not help; ask your organization administrator for the role you need.	`{"detail": "Not authorized for this service"}`, `{"detail": "Operator role or higher required for this action"}`, and the endpoint-specific messages listed under Endpoints.

A request with no token is treated as an anonymous user with no organization membership. On the list endpoints that produces 401; on the action endpoints it produces the same 403 messages you would get for a service outside your organizations.

An id in a path that is not a whole number between 1 and 2147483647 produces 422 Unprocessable Entity with a detail array describing the field, on the endpoints that validate ids. The Endpoints page notes the exceptions.

Response formats¶

Every error on every /api/v1/ path is JSON in the form {"detail": "..."}, regardless of the Accept header you send. You do not need to set Accept.

Successful responses are JSON by default. The web application uses the same endpoints and asks for HTML fragments by sending an HX-Request header. Do not send an HX-Request header from your scripts; if you do, several endpoints return an HTML fragment instead of JSON.

Some endpoints never return JSON because they exist for the web forms:

Creating a downtime answers 303 See Other with a Location header instead of a body.
Editing a service answers 303 See Other; validation messages travel in the Location header.
The recommendation and band-removal endpoints always answer 200 with a small HTML fragment, including for authorization failures.

Each of these is described on the Endpoints page.

Throttling¶

Pulse throttles repeated failed sign-in attempts, and the token endpoint counts as a sign-in.

Failures are counted per email address and calling IP address.
After 5 consecutive failures, the next attempt is delayed by 2 seconds; each further failure doubles the delay (4, 8, 16 seconds and so on) up to a maximum of 300 seconds.
While a delay is running, the token endpoint answers 429 with {"detail": "Too many attempts. Try again in Ns."}, where N is the number of whole seconds left.
A successful sign-in clears the counter.

There is no permanent lockout. Failed attempts against an existing account are recorded in your organization's audit log.

Tip

Cache the token and reuse it for its 8-hour lifetime rather than requesting a new one for every call. A script that retries a bad password in a loop will throttle itself.