> For the complete documentation index, see [llms.txt](https://docs.feathery.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.feathery.io/develop/api-authentication/security-and-troubleshooting.md).

# Security and Troubleshooting

Keep Feathery API credentials safe, recognize them, and fix common authentication errors.

### Best Practices

* **One credential per integration.** Give each integration its own OAuth app and each script its own personal access token, so you can revoke one without breaking the others.
* **Only the access it needs.** Start with Read and add more only when a request needs it. See [Scopes](https://docs.feathery.io/develop/api-authentication/scopes.md).
* **Test before live.** Use the **Test** mode while you build.
* **Store secrets safely.** Keep secrets and tokens in a secrets manager or environment variables. Don't put them in source code, shared configuration files, chat, or email.
* **Short lifetimes.** Choose the shortest expiry that works, and rotate client secrets before they expire.
* **Clean up.** Check **Last used** in the **Developer** tab and revoke credentials nobody uses.
* **When someone leaves.** Their personal access tokens are deleted with their account. If they had an API key or an OAuth app secret, rotate it.
* **Move off API keys.** API keys can do everything and never expire. Move integrations to OAuth apps, then [turn off API keys](https://docs.feathery.io/develop/api-authentication/admin-controls.md#turn-off-api-keys).

### Recognize Feathery Credentials

Feathery credentials start with a prefix, so you and secret scanners can tell them apart:

| Prefix      | Credential            |
| ----------- | --------------------- |
| `fthr_cid_` | OAuth app client ID   |
| `fthr_cs_`  | OAuth app secret      |
| `fthr_oat_` | Access token          |
| `fthr_pat_` | Personal access token |

If a secret or token is shared by accident, revoke it in the **Developer** tab right away and create a new one.

### Troubleshooting

<details>

<summary>401: Invalid or expired access token</summary>

The token expired, was revoked, or its access was reduced. OAuth app access tokens last 1 hour, so request a new one. For a personal access token, check its expiry in the **Developer** tab.

</details>

<details>

<summary>401: Send this token as Authorization: Bearer</summary>

You sent an access token or personal access token with the `Token` prefix. Use `Authorization: Bearer <token>`.

</details>

<details>

<summary>401: Your organization has turned off API keys</summary>

The error reads: "Your organization has turned off API keys. Use an OAuth app or a personal access token, or ask an admin to turn API keys back on." An Admin turned off **Accept API keys**.

</details>

<details>

<summary>401 from /oauth/token: invalid_client</summary>

The client ID or secret is wrong, or the secret was revoked or expired. Check the secret in the OAuth app's **Secrets** list.

</details>

<details>

<summary>400 from /oauth/token: invalid_scope</summary>

You requested a scope the OAuth app doesn't have. Request fewer scopes, or ask an Admin to add the access to the OAuth app.

</details>

<details>

<summary>403: insufficient_scope</summary>

The credential doesn't have access to that area. The `WWW-Authenticate` header names the scope it needs. Edit the OAuth app's access, or create a personal access token with that access.

</details>

<details>

<summary>403: This endpoint only accepts an org API key</summary>

Rotating the API key, `GET /api/form/submission/batch/<form_id>/`, and `/api/form/hidden_field/` still need an API key. Use `GET /api/form/submission/` and `/api/field/hidden/` instead of the last two.

</details>

<details>

<summary>Can't create a token: your organization has turned off personal access tokens</summary>

An Admin turned off **Let members create tokens**, which also stops existing tokens. Ask an Admin to turn it back on, or to create an OAuth app.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.feathery.io/develop/api-authentication/security-and-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
