# Create and protect API keys

Choose the correct target, content environment, and scope; store the secret once; test least privilege; and rotate or revoke it safely.

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.

![A protected credential moving through narrow scope, approved use, rotation, and revocation stages](https://airprompter.com/docs/illustrations/api-key-lifecycle.webp)

Create a credential once, narrow where it works, use it for one integration, then rotate and revoke it deliberately. [Open full-size illustration](https://airprompter.com/docs/illustrations/api-key-lifecycle.webp)

**The secret is shown once**

AirPrompter persists a hash and safe metadata—not the plaintext secret. Copy the new value directly into its destination secret manager. If you lose it, revoke the key and create another one.

## 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**](https://airprompter.com/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](https://airprompter.com/docs/api). 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](https://airprompter.com/docs/api), or review [Direct MCP connections](https://airprompter.com/docs/mcp) for an approved headless host.

---

Canonical: https://airprompter.com/docs/api-keys