> 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/api-clients.md).

# OAuth Apps

Connect servers and integrations to the Feathery REST API with an OAuth app and short-lived access tokens.

OAuth apps are for servers and integrations. They belong to the organization rather than a person, so they keep working when the person who created them leaves. Only Admins can create and manage them.

An OAuth app has a client ID and a secret. Your server exchanges them for an access token that lasts 1 hour, then sends that token with each request.

{% stepper %}
{% step %}

### Create an OAuth App

1. Open your Feathery settings, go to the **Developer** tab, open **OAuth apps**, and choose **New OAuth app**.
2. Name it after the integration that will use it, and choose the **Live** or **Test** mode.
3. Choose its access. See [Scopes](https://docs.feathery.io/develop/api-authentication/scopes.md).
4. Choose when the secret expires: 90 days, 180 days, or 1 year.
5. Click **Create**, then copy the **Client ID** and **Client secret**.

{% hint style="warning" %}
The client secret is shown once. Store it in your server's secrets manager; you won't be able to see it again.
{% endhint %}
{% endstep %}

{% step %}

### Get an Access Token

Exchange the client ID and secret for an access token. Use your region's [API host](https://docs.feathery.io/develop/api-authentication.md#api-host-for-your-region):

```bash
curl https://api.feathery.io/oauth/token \
  -u "<client ID>:<client secret>" \
  -d grant_type=client_credentials
```

```json
{
  "access_token": "fthr_oat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "forms:read submissions:read"
}
```

You can send `client_id` and `client_secret` in the form body instead of the `-u` header. To get a token with less access than the OAuth app has, add a space-separated `scope`, like `-d "scope=forms:read"`.
{% endstep %}

{% step %}

### Call the API

Send the access token as a Bearer token:

```bash
curl https://api.feathery.io/api/form/ \
  -H "Authorization: Bearer <access token>"
```

Access tokens last 1 hour, and there's no refresh token. Request a new access token before the old one expires, or when a request returns `401`.
{% endstep %}
{% endstepper %}

### Rotate a Client Secret

Each OAuth app can have two active secrets, so you can rotate without downtime:

1. Open the OAuth app under **OAuth apps** in the **Developer** tab and choose **Add secret**. Copy the new secret.
2. Deploy the new secret to your servers, a few at a time if you can.
3. Watch **Last used** for the old secret in the OAuth app's **Secrets** list. Once it stops changing, revoke the old secret.

Revoking a secret also ends the access tokens it issued. Admins get an email 30 days and 7 days before a secret expires.

### Change or Delete an OAuth App

Open the OAuth app to rename it or change its access. Taking access away ends any access token that holds it, so your server requests a new one.

Deleting an OAuth app ends all of its secrets and access tokens right away.

### Keep It Safe

See [Security and Troubleshooting](https://docs.feathery.io/develop/api-authentication/security-and-troubleshooting.md) for best practices and fixes for common errors.


---

# 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/api-clients.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.
