How do I use an API key from an outside program?

You will have made a program call this site with a key.

Before you start

You need a key that holds the scopes the calls need. Keep it on the server side: never put it in a web page or mobile app.

Steps

1. Put the key in a request header named X-API-KEY, for example X-API-KEY: ak_….
2. Call the site's tRPC API under /api/trpc/. It is the only surface that reads keys; there are no separate REST endpoints for them.
3. Check the status of each response (below).

What you will see

• Success when the key is valid and holds the scope the call needs.
• 401 when there is no key, or it is wrong, revoked or expired. The response does not say which, so check with the person who issued it.
• 403 when the key lacks a scope the call needs; the message names it. Also 403 for calls about "the calling user" (such as "my tasks"), because a key is not a person: ask for the wider permission instead.
• 400 for a missing or invalid field, as for people.

If something goes wrong

• A key stops working at once when it is revoked, and when the person who created it is deactivated.
• When a key is present its scopes are the only authority; sending a session cookie as well adds nothing.
• There is no limit per key, only the site's general limit per address (about 1000 requests a minute).
• A key works on any hostname the install answers on and cannot be restricted to an IP.