API Keys
An API key lets your own code — a data warehouse sync, a reporting script, a CI job — read your organization’s Apptonomy data through the Public API, and, if you allow it, start audits, write draft listings and change recommendations’ workflow state. Keys are managed in Org Settings › API Access.
A key belongs to the organization, not to the person who created it. It never acts as a user: it reads and does only what its scopes allow, in the one organization it was created in, and it keeps working when its creator leaves. AI clients such as Claude do not use API keys; they sign in as a member (see MCP).
Before you start
- You need to be the organization’s Owner or a Manager. Standard members don’t see API Access.
- Creating and rotating keys needs a plan that includes API access, which is Enterprise (see Plans & entitlements). On other plans the page says “Your plan does not include API access.” Listing and revoking existing keys works on any plan.
- An organization can have at most 10 active keys. Revoked and expired keys don’t count.
Create a key
- Open Org Settings › API Access and click Create API key.
- Name it after the system that will use it, for example “Data warehouse sync”. Create one key per system, so each can be revoked on its own.
- Under What this key can read, tick only what that system needs. There is no default; at least one is required. Under What this key can do, tick an action only if the system takes it.
- Choose when it Expires: 30, 90, 180 or 365 days, or Never.
- Click Create key.
What a key can read
| Scope | Label in the app | Gives access to |
|---|---|---|
organization:read | Organization | The organization’s name and settings |
projects:read | Projects | Projects and their apps |
audits:read | Audits | Audit runs and their results |
recommendations:read | Recommendations | Audit recommendations and their evidence |
scores:read | Scores | Listing scores |
revisions:read | Revisions | Listing revisions |
impact:read | Impact | Measured impact of published changes |
analytics:read | Store analytics | Daily App Store and Google Play numbers (also needs a plan with store analytics) |
revenue:read | Proceeds | Store proceeds and revenue (not served yet) |
sensitive:read | Personal data | Names, emails and user ids on anything else the key can read |
Without sensitive:read, personal fields are left out of every response and the response says which ones (a fields_omitted warning). Leave it off unless the system genuinely needs to know who did what.
What a key can do
| Scope | Label in the app | Lets the key |
|---|---|---|
audits:write | Start audits | Start audits of the organization’s projects (Actions) |
revisions:write | Edit revisions | Write text into a project’s draft listing for a person to review and publish (Actions) |
recommendations:write | Update recommendations | Accept, defer, resolve, dismiss or reopen a recommendation (Actions) |
A write scope only acts: to follow an audit a key started, it also needs audits:read; to read the draft, revisions:read; to read a recommendation’s state, recommendations:read. No key can publish a listing.
Copy the key once
After you click Create key, Apptonomy shows the full key once:
a7y_live_<key id>_<secret>
Click Copy key, put it in your secret manager, then click I’ve stored the key. Apptonomy keeps only a one-way fingerprint of the secret and cannot show the key again. If you lose it, rotate the key or create a new one.
The first part, a7y_live_<key id>, is the key’s prefix. It’s what the key list shows and it is safe to log or paste into a support request. The secret after it is not.
Use the key
Send it in the Authorization header on every request:
curl -s https://api.apptonomy.ai/v1/organization \
-H "Authorization: Bearer $APPTONOMY_API_KEY" \
-H "Accept: application/json"
Never put a key in a URL. A request with a key anywhere in its path or query string is refused with 400 invalid_request (detail credential_in_url) before the key is even looked up, and you should treat that key as exposed and revoke it. The quickstart walks through a first set of requests.
The key list shows each key’s scopes, status, when it expires and when it was Last used. Last used is updated at most every 15 minutes, so a key in constant use can look up to a quarter of an hour behind.
Rotate a key
Rotate on a schedule, and whenever someone who had the key leaves.
- In the key’s row, click Rotate.
- Choose what happens to the Old key: revoke it now, or keep it working for 1 hour, 24 hours or 7 days while you deploy the replacement. An overlap never extends the old key past its own expiry.
- Click Rotate key and copy the replacement, exactly as when creating one.
The replacement has the same name, scopes and term. Rotating needs a plan with API access.
Revoke a key
Click Revoke in the key’s row. Revocation is immediate and permanent: the key’s next request, in any region, answers 401 invalid_credential. A revoked key can’t be turned back on — create a new one.
If a key leaks
If a key was committed to a repository, pasted into a chat, printed in a log or sent in a URL:
- Revoke it (or rotate it with Revoke the old key now). It stops working on its next request.
- Deploy the replacement to the system that used it.
- Check Access history on the same page for requests you don’t recognise. It records every request each key made — allowed or refused, with the operation, the project or resource it named and the time — for 90 days, and you can export it as CSV. It never records keys or the data returned.
- Tell us at security@apptonomy.ai with the key’s prefix (never the full key) and when it leaked.
If you don’t know which key is affected, Turn off all programmatic access under Emergency access controls on the same page stops every API key and every AI client connection at once. The dialog says how many keys and connections stop. Nothing is deleted: turning access back on restores exactly what was working. You can also turn off only API keys or only AI clients (MCP). Every change, with who made it and the reason you give, is in the organization’s audit log.
Keeping keys safe
- Store keys in a secret manager (your cloud provider’s, 1Password, Vault) or your CI system’s encrypted secrets, and read them from an environment variable at run time. Never hard-code a key in source code or commit it, not even to a private repository.
- Never use a key in a browser, mobile app or any code you ship to users. Anyone can read a key from client-side code. Call the API from your own server and send your users only the results.
- Keep keys out of logs. Don’t log request headers. Use the prefix when you need to say which key did something.
- One key per system, the fewest scopes it needs, and an expiry. A leak then exposes one system’s read access for a bounded time.
- In CI, give each pipeline its own key, scope it to what the job reads, and mask it in job output.
Related
- Getting Started — a first request with a new key
- Resources and Actions — what a key can read and do
- Weekly Report Example — a complete walkthrough in curl and JavaScript
- MCP — connecting AI clients such as Claude
- Members & Roles — who is an Owner or Manager