API tokens

Your code calls the API with an API token. The Organization holds it, not the person who made it, so it keeps working when they leave the Organization or lose their access.

Who may make one

The owner and admins can make tokens, on the API tokens screen. Members cannot see it. An admin makes tokens only for the Projects they can reach, and sees only those tokens. Only the owner makes a token that reaches every Project. See Members and Roles.

An Organization holds up to 25 tokens at once. A revoked token does not count; an expired one counts until you remove it.

Making a token

1. In the sidebar, open API tokens.
2. Press New token.
3. Give it a name, such as the tool that will use it. Each token in the Organization has its own name.
4. Choose what it reaches: one Project, or every Project.
5. Choose its kind, and when it expires.
6. Press Create token, and copy the token. It is shown this one time, and You Up? cannot show it again.

A token starts with uup_api_. Keep it where you keep passwords, and never in a web page or a public repository.

The two kinds

• Read-only: reads monitors, results, uptime and incidents. It changes nothing.
• Full: can also create, change, pause and delete. It may do what an admin may do through the API.

No token can change billing, the Plan, Members, the Organization, or tokens themselves, or make or delete a Project.

What it reaches

A token made for one Project sees that Project alone. Any other Project answers as if it did not exist. A token for every Project reaches each Project the Organization has, including those made later.

When a Project is deleted, the tokens made for it stop working.

When it expires

A token expires after 30 days, 90 days, 365 days or Never, as chosen when it was made. The owner and the admins who see it get an email 7 days before it expires.

An expired token stops working, and its row stays listed, marked Expired, until you press Remove.

To change a token’s kind, reach or expiry, make a new token, swap it into your code, and revoke the old one.

Revoking a token

On API tokens, press Revoke on the token’s row. Code that uses it stops working at once, and you cannot undo it. The owner and the admins who see the token get an email.

An act a token took, such as resolving an Incident, stays shown as the token’s, by its name, after it is revoked.