API keys

What a key is

• A key is atk_ followed by 64 hex characters. It's shown once, when it's made. AttackDesk stores only a SHA-256 hash of it. The Keys page shows its first characters so you can tell keys apart.
• Every key belongs to one company and to one person on it. Someone who manages every key can make a key for someone else; it is still that person's key. It acts as them, and what it spends counts as theirs.
• People with the Every key permission (owners, admins, developers and managers, unless changed on their Team page) see and manage everyone's keys on API Keys. Everyone else sees and manages only their own, and makes their own only with Make their own API keys.
• Keys are made, changed, paused and deleted only on the dashboard. No API route manages keys.

Operations

• Each API route needs one operation, such as phone.messages.send or sandbox.exec. The API reference gives the operation for every route.
• A key holds a list of operations. Choose them under Access when you make or edit a key. Full access gives every available operation your role allows, except ones that remove things. Restricted lets you choose them one by one.
• Operations that remove things are never included on their own: releasing a phone number, deleting a call recording, deleting a box and deleting the company. Tick them yourself under Restricted.
• Some operations only work with another one on the same key:

• A key made before operations existed keeps exactly what its old switches reached (code, phone, email, address lookup, hosting). Operations added since don't join it.
• Buying funds isn't an operation. It's off on every new key. Only an owner can turn on Add funds for a key, with a limit for one purchase and a limit for the month.
• A key's AI models setting (no AI, all models, or only some) is saved with the key. No API route uses it yet: keys don't reach AI models.

Access levels

Each operation also has a level: who may hold it. It's checked against the key's person on every call.

Technical areas are phone, email, DNS and hosting, each at configure or provision (provision includes configure). Only an owner hands an area to a developer, and changing the developer's role or removing them ends every area they were handed. The dashboard has no page for handing areas out yet, so for now technical operations are for owners and admins.

Some routes also check the person's own permissions on their Team page:

• Git pull needs Download and pull the code. Git push and box pushes need Push and upload code.
• Starting a box needs Create test environments, Spend on environments and Download and pull the code.
• Publishing a preview needs Push and upload code. Sending the business to carriers for texting needs an owner or admin.

When the check refuses a call, the answer is 403 with one of these:

A key is capped by its person

• A key acts as its person as they are now. If their role or permissions change, their keys change with them on the next call.
• When you save a key, you can't give it more than you may do, or more than its person may do. The Keys page greys those operations out, and the server refuses them.
• API key limit. On a person's Team page, someone with the Team permission can set the most that person's keys may do. Their keys are held to it on every call, and a key can't be saved with more.
• Spending limits. What a person's key spends counts toward the company's limits and toward that person's own limits, unless their limit is set to leave their API keys out. See Limits.
• When a person is removed from the company, their keys are revoked (a hosted app's key they approved keeps working). When a company is deleted, its keys stop at once.

The company app's keys

• A connected copy of AttackDesk and a company's hosted app each have a key of their own. These keys carry many people's traffic, so they are shared, not one person's.
• A shared key acts as the signed-in person when the call carries that person's sign-in (the app sends it in the X-AttackDesk-Actor header). The call is then checked against that person and charged to them. A sign-in that doesn't check out refuses the call.
• With no signed-in person, a shared key can use only operations open to any member, as company usage. Others answer 403 actor_required.
• With no signed-in person, a shared key can't use AI worker boxes or publish. Git never accepts a shared key. Use a person's own key for those.

Expiry, pausing, deleting

• A key can expire after 7, 30 or 90 days or a year, or never. After it expires, calls answer 401 invalid_key.
• Pausing a key refuses it (401) until it's switched back on. Deleting a key is permanent.
• The Keys page shows when each key was last used, to the nearest few minutes.

A key's spending limit

• A key can have its own limit in dollars ($5, $25, $100, an amount you type, or no limit) that resets every day, week or month. Periods are in UTC; a week starts on Monday.
• It counts only what this key spends. Company and person limits apply as well.
• It's checked in the same database write as each charge, so calls made at the same moment can't all pass it.
• A charge that would go over it answers 429 spend_limit_reached. Once the limit is used up, the key is refused with 401 invalid_key until the period resets or someone raises the limit.

Keys found in git pushes

• The code server checks every push for secrets. A push that adds a secret is refused.
• Any AttackDesk key found in a push, or in a version of the code uploaded on the dashboard, is switched off at once, whoever it belongs to. The push's output says how many keys were switched off.
• The key's page then shows where it was found and on which day. Make a new key on API Keys.

AttackDesk switched off 1 AttackDesk key(s) found in this push. Make new ones on your API Keys page.