API Keys: Creating, Limiting and Revoking Them

An API key lets your own software read hours, members, projects and activity out of SCREENish, and — with the wider scope — write manual time back. Create one under API & Integrations > API keys: type a label, choose the scope, press Create key. The key appears once, in a yellow box, with a Copy button. It is never displayed again.

The two scopes

• Read only — the account, team members, projects, time entries, timesheets, activity, activity reviews and face-check verdicts. This is the right choice for a dashboard, a report or a spreadsheet job.
• Read + write — the same, plus creating manual time entries and managing webhook subscriptions. Automation platforms that register their own webhook need this one.

Limiting a key to your servers

The Allowed addresses field takes a list of IPv4 or IPv6 addresses, or ranges in CIDR form (203.0.113.5, 10.0.0.0/8). From anywhere else the key is refused, even though it is valid. Leave the field empty and the key works from any address. Use it whenever the caller is a server with a fixed address; skip it for a laptop or a cloud automation whose addresses change.

Using the key

Send it as a bearer token in the request header:

Authorization: Bearer sk_live_...

A key passed in the address bar as a query parameter is refused even when correct, so that it never ends up in a server log or a browser history.

Seeing what a key did

Press Activity on a key's row. Every call it has made is listed: the moment, the address it came from, the endpoint, the filters used, the answer's status, how many records were returned and how long it took. The key's row itself shows when it was last used and how many times. This is the record to reach for when you want to know what a vendor's integration has actually been reading.

Limits

• 120 requests a minute per key. Beyond that the answer is a 429 with the seconds to wait; every answer carries the remaining budget in its headers.
• A request may span at most 92 days, and lists return up to 200 rows a page.
• A key works while the account has an active subscription, and is deleted when the account closes.

Revoking

Press Revoke. The key stops working immediately and stays in the table, greyed out and dated, so the record of what it did is not lost. Revoke and re-create rather than reuse when a key has been pasted somewhere public, when a contractor leaves, or when you simply cannot find it — there is no way to display an existing key again.

Endpoint-by-endpoint documentation, with parameters and answer shapes, is on the developers page; the machine-readable description is at /api/v1/openapi.json.