Authentication

Create, rotate and revoke API keys, and send them with the Authorization header.

Every request to https://api.incomegraph.net/v1 carries an API key in the Authorization header:

Authorization: Bearer igk_your_key_here

The API reference and its Swagger UI test console are public to read; only API calls need a key. In the console, tap Authorize and paste the key.

Create a key

Sign in and open your account page.
Under API keys, give the key a name (for example laptop or ci), choose its access, and choose Create API key.
Copy the key immediately. It is shown once. Income Graph stores only a SHA-256 hash, so a lost key cannot be recovered; create a new one instead.

You can hold up to five active keys. Creating keys needs an active subscription.

Read-only and read-write keys

Every key has a scope, chosen when you create it and shown next to the key on the account page:

Scope	Can do
Read only (default)	Everything that reads: `GET` endpoints and the calculator.
Read and write	All of the above, plus create, update and delete graphs.

You can change a key’s access later without replacing it: on the account page, use the access menu next to the key. Choosing Read and write asks you to confirm, because anything holding that key can then create, update and delete your graphs; going back to Read only takes effect at once. Granting write access needs an active subscription; reducing it never does. Changing access is only possible from the signed-in account page, never with an API key, so a leaked read-only key cannot upgrade itself. Keys created before scopes existed show as Read only. Use a read-only key for anything that only looks at your graphs, and a read-write key only for the agents and scripts you want to edit them; if a read-write key leaks, revoke it first. A write with a read-only key is refused with 403 insufficient_scope and nothing is changed.

Rotate a key

Rotation never needs downtime because old and new keys work side by side:

Create a new key and deploy it wherever the old one is used.
Check that traffic works with the new key (GET /v1/me names the key making the request).
Revoke the old key from the account page.

Revoke a key

Choose Revoke next to the key. It stops working on the very next request. You can list and revoke keys even after a subscription lapses.

Keep keys safe

Treat a key like a password. Keep it in an environment variable or secret manager, never in source control, a web page or a mobile app. Keys start with igk_ so secret scanners can recognise them.
Use one key per integration so you can revoke one without breaking the rest.
If a key leaks, revoke it first, then create a replacement.

What an authentication failure looks like

Situation	Status	`error.code`
No `Authorization` header, or not a Bearer token	401	`missing_api_key`
Unknown, malformed or revoked key	401	`invalid_api_key`
Valid key, but the owner has no active subscription	403	`subscription_required`
Valid key, but the last payment failed	403	`subscription_past_due`
A write with a read-only key	403	`insufficient_scope`

Subscription status is checked on every request, writes included, so cancelling stops API access immediately and resubscribing restores it with the same keys. No data is returned with any of these responses.