One key, only what you allow.

An API key is a Bearer token that acts as the person who created it. Each key carries scopes, and every route names the one scope it needs. Keys are created in the app and never by the API itself.

Create a key

In the app: Settings → API tokens. The form asks for a name, an access level (read-only or read and write), an expiry (never, 30, 90 or 365 days; the form starts at 90), the scopes and, when agency mode is on, the clients the key may see.

• The key is shown once. up4 stores only a SHA-256 hash, so a lost key cannot be shown again; create a new one.
• Every key starts with pls_.
• Without an explicit scope list, a read-only key gets every .read scope and a read and write key gets every read, write and delete scope.
• A key cannot create, rotate or revoke keys. Those routes answer only to a signed-in browser session.
• Rotate in the app issues a new key with the same name, scopes, access level, clients and expiry. The old key keeps working for at most 24 more hours, so you can switch over without downtime.
• up4 records when a key was last used.

Send the key

Put it in the Authorization header as a Bearer token. GET /me needs only self.read and shows what the key can do:

export UP4_API_KEY="pls_…"

curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY"

{
  "data": {
    "api_key_id": "…",
    "api_version": "2026-05-07",
    "auth_method": "api_key",
    "client_set": { "All": true, "CompanyLevel": true, "IDs": null },
    "org_id": "…",
    "org_role": "owner",
    "scopes": ["self.read", "monitor.read", "monitor.write", …],
    "user_id": "…"
  }
}

scopes comes in no fixed order. A team key also shows team_id. client_set is explained on the client scope page.

Scopes

A scope is <resource>.read, .write or, for monitors, .delete. Each reference page states the scope per operation; the table shows what the families cover.

You may also see api_key.read and api_key.write on a key. No public route needs them.

A key that is read-only by access level is refused on every write route, even if its scope list contains a write scope. The role of the person who created the key applies as well: a viewer cannot write with a read and write key.

When the key is refused

The shape of these bodies is on the responses page; every code is in the error catalogue, for example insufficient_scope.

Company-level routes such as /organization answer 404 Not found to team keys and to keys that cannot read company-level resources.

Common mistakes

• Writing bearer in lowercase, or leaving out the word. Both give 401.
• Reading 403 as a bad key. A bad key is 401; 403 means the key is valid but lacks the scope or the write access.
• Creating a key as read-only and adding write scopes later in your head. Create a read and write key, or rotate to one.
• Keeping keys in shared chat or in code. Revoke a leaked key in the app; it stops working at once.
• Using a key tied to one person for an integration. When that person leaves the Company, the key answers 401.