Authentication and Roles

Every request to the OpsFusion API must include an API key. This page explains how to send it, what the roles allow, and how to handle keys safely.

Sending Your Key

Put your key in the Authorization header. Both formats work:

Format	Example header value
Raw key	YOUR_API_KEY
Bearer	Bearer YOUR_API_KEY

Other things to know:

• Send the complete key. A partial or altered key is rejected.
• The account ID in the URL is the ID of your account. See Finding Your Account ID.
• A key only works for the account that owns it. Using it with another account’s ID returns 403.
• The account must be active, or on a trial that hasn’t expired.
• Requests with a body need the Content-Type: application/json header.

To create a key, see Create an API Key.

Roles

Each key has one to three roles. If a key has several roles, it gets everything any of them allows.

Endpoint	Admin	Read Only	Alert Push
POST /push/alert	Yes	No	Yes
POST /push/alertmanager	Yes	No	Yes
All GET endpoints (account, API keys, audit, invites, teams, alerts, users)	Yes	Yes	No
POST /invite, DELETE /invite/{email}	Yes	No	No
POST /team, PATCH /team/{teamId}, DELETE /team/{teamId}	Yes	No	No
POST /team/{teamId}/member, DELETE /team/{teamId}/member/{username}	Yes	No	No
PATCH /team/{teamId}/alert/{alertId} (acknowledge or close)	Yes	No	No
DELETE /user/{username}	Yes	No	No

All paths are under /account/{accountId}. The reference pages list the role each endpoint needs.

Changes Take a Few Minutes

When you delete a key or change its roles, the change can take a few minutes to apply. During that time, the old key may still work.

401 and 403

Status	Meaning
401 Unauthorized	The Authorization header is missing or blank
403 Forbidden	The header is present but the request is denied

A 403 can mean any of the following:

• The key is incorrect or doesn’t exist (for example, it was deleted)
• The key belongs to a different account than the one in the URL
• The account is inactive, or its trial has expired
• The key’s roles don’t allow the endpoint
• The endpoint isn’t available in the API

A request to a path that doesn’t exist also returns 403.

See Errors for all status codes.

Security Tips

• Use keys on servers only. The API doesn’t support browser requests, and a key in front-end code is visible to everyone.
• Use the narrowest role. Give monitoring tools Alert Push, and reporting tools Read Only.
• Use one key per tool. You can then delete one key without breaking the others.
• Store keys in a secrets manager. Don’t put them in source code or chat messages.
• Rotate keys regularly. Create a new key, update your tools to use it, then delete the old key in the app.
• Delete keys you no longer use. Your account can have up to 10 keys.

If a Key Leaks

Delete the key in the app right away, then create a replacement. The deletion can take a few minutes to take effect. Check the Audit Logs for activity you don’t recognize.