Name a key for the integration that uses it
A key named “test” becomes hard to identify once several applications use your account. A name such as “signup-staging-reader” or “support-prod-sender” tells the next person where the credential belongs and why it exists.
Create separate keys for independent integrations. If a staging agent no longer needs access, you should be able to revoke its credential without stopping production email. Record the owner, environment and secret-store location alongside the integration documentation, but never copy the secret itself into that record.
Choose permissions for the task
In InboxIt, open API keys in the intended workspace. The same workspace key can be used with the HTTP API, CLI or a coding agent that calls those tools. “For the CLI” is an intended use, not a special permission level.
- A reader needs inbox and message-reading permissions.
- An agent that creates test inboxes also needs inbox-creation permission.
- A sender needs emails:send; grant reading or creation permissions only if its workflow needs them.
Check the permissions shown for the selected dashboard option before creating a key. The current dashboard offers predefined groups, while the API reference documents individual scopes. Choose the smallest supported set that fits the integration.
Keys belong to a workspace. If a valid key cannot see an inbox, first check that both belong to the same workspace rather than widening permissions immediately.
Store the secret once, in the right place
The dashboard displays a newly created secret once. Copy it into your server’s secret manager or protected environment configuration. Use the HTTP Authorization header for API calls. The CLI accepts a workspace key through INBOXIT_TOKEN; see the CLI configuration guide.
Do not put keys in frontend bundles, screenshots, support tickets or committed configuration files. A browser variable is visible to users even if its name suggests that it is private. Ensure request logging does not record Authorization headers.
When giving an agent access, pass the credential through its execution environment instead of asking it to paste the key into generated code. Review which tools and workspace that agent can access.
Understand rotation before clicking Rotate
InboxIt’s Rotate action replaces the token and immediately invalidates the old one. It preserves the existing key’s permissions and expiry. Rotation is therefore not an extension of its lifetime, and an integration still using the old value will start failing authentication.
- Identify every process that uses the key and prepare its configuration update.
- Rotate the key, then securely capture the newly displayed secret.
- Update the integration and restart or reload configuration as required.
- Run a permitted request and confirm successful authentication.
If a planned cutover needs overlap, create a separate replacement key first, update and verify the integration, then revoke the old key. Keep that overlap short. If the old key was exposed, revoke it promptly rather than leaving it active for convenience.
Diagnose an access error without exposing a key
A 401 response generally calls for checking authentication: the key may be missing, expired, revoked or replaced. For a 403, investigate permissions, workspace context and account eligibility. Repeating the same request will not repair those conditions.
When asking for support, share the key’s name or visible prefix, the endpoint, status code and approximate time. Do not send the complete token. The errors and retries guide explains the status categories.
Make key review part of maintenance
Review unused integrations, upcoming expirations and who owns each credential. Remove abandoned keys and test that replacement credentials are installed before an old one expires. Do not confuse an API key with a webhook signing secret: one grants access to the API; the other helps authenticate events sent to your endpoint.
For an agent that only checks signup messages, begin with read and inbox-creation access as needed, not general sending access. The agent email guide shows how to keep the workflow bounded.
