A practical workflow for choosing bot permissions, storing organization API keys and replacing access without losing track of the workers that use it.
A bot that updates listings or answers clients needs a clear job and a controlled way to access your organization. Before handing over an API key, decide what the bot may do, who operates it and how you will replace its access.
This guide uses illustrative agency workflows. The job descriptions below are planning examples, not literal API scope names or a promise that every API supports the same controls.
Start with the bot's job
Write a short operating brief before choosing permissions. “Help our team” is too broad to review. “Read selected conversation history and draft replies for an operator” gives you something concrete to check.
| Illustrative integration | Intended work | Questions before enabling access |
|---|---|---|
| Inventory reporter | Prepare a daily list of available profiles | Does it need to change listings, or only read them? |
| Reply assistant | Read conversations and send approved responses | Which conversations and actions can the API actually restrict? |
| Listing assistant | Prepare and update profile listings | Can it work without reading account credentials? |
In AllProfiles, organization tokens use the documented Bearer authorization header. Access also depends on the issuing actor's current permissions, organization membership and status, token scopes, expiry and revocation. Reading profile credentials requires a separate scope. Check the current authentication and permissions reference when selecting access; a token's label does not define its permissions.
For example, a listing assistant's brief might say: “Prepare draft listings for review. Do not retrieve account passwords or change billing.” Compare that brief with the permissions the API actually exposes. If its controls cannot express the required boundary, change the workflow before enabling the bot.
Keep an integration register, not a spreadsheet of keys
OWASP recommends managing secrets with controlled access and a defined lifecycle, including rotation, revocation and expiration. Use a restricted secret-management system for the values themselves, and keep an operational register that contains only references and responsibilities. See the OWASP Secrets Management Cheat Sheet.
An illustrative register entry could look like this:
| Field | Illustrative value |
|---|---|
| Integration | Listing assistant |
| Operator | Agency operations lead |
| Environment | Production |
| Approved job | Prepare profile drafts for review |
| Secret reference | Internal secret-store entry for this integration |
| Dependencies | Listing worker and its scheduled job |
| Review trigger | Job change, operator change or scheduled access review |
Do not include the token value in that register. Where supported, separate credentials by integration and environment so the dependency list remains understandable. A single shared credential makes it harder to identify everything that must change during replacement.
Load the key where the bot runs
Have the worker load its credential at runtime from your approved secret store. An environment variable can deliver a value to a process; it is not, by itself, a complete storage or access-control strategy. Restrict who can retrieve the value, and check whether deployment tooling or diagnostic output exposes it. Never log plaintext secrets, including authorization headers, as OWASP’s secrets-management guidance explains.
Keep credentials out of source files, screenshots, support tickets and prompts sent to external tools. Give another operator the secret-store reference and setup instructions rather than copying the key into a handover message.
Send requests over HTTPS using the API's documented authorization header. Do not put keys in query strings: URLs can enter server logs and other records. These transport practices follow the OWASP REST Security Cheat Sheet.
Test the operating boundary before enabling a schedule
Use a test environment where the provider offers one. Start with a read request and confirm the organization and response match your intended setup. Review the granted permissions against the operating brief before enabling writes.
For the illustrative listing assistant, the first review could include:
- Confirm that returned listings belong to the intended organization.
- Check that request logs omit credentials and sensitive response fields.
- Test the draft workflow with a disposable fixture in an appropriate test environment.
- Confirm that an operator can stop the scheduled worker.
Avoid using real charges, deletions or client messages as casual permission tests. A successful read request establishes that particular path works; it does not establish that every action or restriction is correct.
Replace a key with a short, repeatable runbook
For a planned replacement, first identify the workers that use the current credential. Follow the provider's supported process to issue or replace it. If overlapping credentials are supported, load and test the replacement, switch the workers, then retire the old one and verify it is rejected. If overlap is unavailable, plan a pause around the change.
This is a conditional operating pattern, not a claim that AllProfiles supports automatic rotation or an overlap window. Record the result and update the dependency register. Choose your review schedule according to the integration's risk and operating requirements rather than treating a fixed number of days as a universal rule.
Treat an exposed key as an incident
A suspected leak should not wait for the next planned review. Promptly revoke the exposed credential or rotate it so the old value no longer authenticates. Inspect relevant activity and check where copies may remain.
If a key reached Git, removing it from the latest file is not enough: repository history, clones and forks can retain it. GitHub's guide to removing sensitive repository data puts credential revocation or rotation first and explains the coordination needed for history cleanup. Never restore an exposed key as a rollback shortcut.
Before handing an integration to another operator, make sure they can answer three practical questions: where its credential is managed, which worker uses it and how to stop that worker. Keep those answers alongside the operating brief and the current API documentation.
