Create and protect API keys

An AirPrompter API key combines three decisions: where it works, which content maturity it can read, and what actions it can perform. Make those choices for one integration instead of reusing a broad credential everywhere.

Understand the three choices

Target: where the key works

Target	Intended boundary	Write behavior
Personal	Your Personal Library	Can be read-only or read/write when the target allows it
Organization	One authorized organization	Read-only
Workspace	One authorized workspace	Read-only

The target is not a label. It is the resource boundary carried by the credential. A legacy key without an explicit binding remains Personal; it does not inherit Team access.

Content: test or live

Choice	Content maturity
Test	Includes authorized draft content
Live	Published content only

ap_test_ and ap_live_ describe the content maturity selected for the key. They do not identify whether AirPrompter itself is deployed in a development or production AWS environment.

Access: read or write

• prompts.read lets a permitted client browse the AirPrompter resources and metadata available to its target.
• prompts.write includes read and can allow eligible Personal key operations such as running or advancing workflows and saving prompts.
• Organization and Workspace keys remain read-only. Team writes require OAuth, even if a client presents prompts.write.

Choose Read only unless the integration has a specific, reviewed Personal write job.

Before you create a key

Decide:

1. the one service, script, or agent that will use it;
2. the narrowest target that service needs;
3. whether draft content is allowed;
4. whether the service truly needs to change Personal prompts or workflow run state;
5. where the secret will be stored; and
6. who will rotate or revoke it when the integration changes.

Do not create a key merely to work around a failed OAuth connection or a denied Team write.

Create the key

1. Sign in to AirPrompter.
2. Open Account → Developer.
3. Confirm that the page heading is Developer.
4. In API keys, select Create API key.
5. Choose the Target.
6. Choose Test for authorized draft content or Live for published content only.
7. Choose Read only or, for an eligible Personal target, Read & write.
8. Create the key.
9. Copy the complete secret from the show-once dialog directly into the intended secret manager or protected environment setting.
10. Close the dialog only after the destination has saved the value.

Expected result: the key appears in Active keys with a non-secret display prefix, target, environment, scopes, created date, and status. The full secret cannot be reopened.

Test least privilege

For REST, begin with the identity request from Choose the AirPrompter API surface. For an MCP-compatible headless client, begin with a read-only list or find action against harmless staged data.

Verify:

• the key resolves the intended owner and target;
• a Test key can read only authorized draft content;
• a Live key does not expose drafts;
• a read-only key cannot perform a write operation; and
• an organization or workspace key cannot perform a Team write.

Expected result: the intended read succeeds and an action outside the selected boundary fails closed.

Store and operate the key safely

• Put the secret in a secret manager or protected runtime environment variable.
• Keep it out of repository files, screenshots, browser bookmarks, ticket text, chat messages, analytics, and application logs.
• Send it only to the AirPrompter API or the approved AirPrompter MCP connection endpoint.
• Use a separate key for each integration and environment so one credential can be revoked without stopping unrelated work.
• Review Last used and status in the Developer panel during normal access reviews.
• Remove the old secret from its runtime after rotation.

Showing a display prefix in the AirPrompter UI helps identify a key; it is not sufficient to authenticate a request.

Rotate a key without losing control

1. Create a replacement with the same narrow target, content environment, and required scopes.
2. Store the new secret in the integration’s protected configuration.
3. Run the harmless identity or discovery proof.
4. Switch the integration to the replacement.
5. Confirm successful use from the new key’s metadata or the integration’s sanitized health check.
6. Revoke the old key.
7. Remove the old value from every runtime and secret store that held it.

Expected result: the integration works with the replacement and the old key appears inactive and can no longer authenticate.

Revoke a key

1. Open Account → Developer.
2. Find the active key by target, display prefix, environment, and creation date.
3. Select Revoke and confirm the intended key.
4. Stop or update the integration that used it.
5. Test that the old value receives an authorization failure.

Revoked and expired credentials remain available under Show inactive keys for history, but cannot be used.

Apply keys to day-to-day work

Read-only account health check

Give a monitoring job a dedicated read-only Live Personal key. Let it call /v1/me and /v1/entitlements; do not reuse the credential in an authoring agent.

Personal workflow automation

If an approved Personal headless workflow needs run/write operations, create a dedicated Personal read/write key, prove the exact actions, and keep it separate from human OAuth connections.

Team reporting

Use a read-only organization or workspace key for the allowed report inputs. If the job later needs to change Team resources, redesign it around an eligible OAuth connection rather than broadening the key.

Troubleshooting

The Create button is disabled

AirPrompter has not returned an eligible target for the account, or key data is still loading. Confirm account access and retry from Account → Developer.

Read & write is unavailable

The selected target does not allow key-based write. Organization and Workspace targets are intentionally read-only; Team writes require OAuth.

The secret was not saved

Do not try to reconstruct it from the display prefix. Revoke that key and create a replacement.

A previously working key returns 401

Check whether it was revoked or expired, whether the entire secret is still present in runtime configuration, and whether the header format is correct. Rotate instead of logging the secret for diagnosis.

The wrong content is visible

Stop the integration. Verify the selected target and Test/Live choice, revoke the mis-scoped key, and create a correctly bounded replacement.

Completion checklist

• The key belongs to one named integration.
• Its target is the narrowest resource boundary that works.
• Test or Live matches the content maturity the job may read.
• Read/write is used only for a reviewed Personal job.
• The complete secret exists only in approved protected storage.
• A permitted action succeeds and an out-of-scope action fails.
• Rotation and revocation have a named owner.

Next steps

Use the key with the two current REST API routes, or review Direct MCP connections for an approved headless host.