# OAuth apps

Let your product act for a person in HQ with their consent. Authorization code with PKCE, refresh rotation, revocation and what an app can never do.



An **OAuth app** lets other software act for one person in HQ, in the one organization they pick,
after they approve it. Use it when your product is used by people in organizations other than yours.
For your own automation, use an [API key](/docs/api/authentication/) instead.

An app never does more than the person who approved it can do there. On top of that, an app can
**never**:

* send a prompt, answer a question card or interrupt, in any session;
* create a session, or write or run a schedule (a schedule's run is a prompt);
* use anyone's personal Claude or ChatGPT login;
* read the organization's API keys or manage its webhooks.

## Register an app [#register-an-app]

In HQ, open **Settings**, then **Developers**, then **OAuth apps**, and choose **Register app**
(owners and admins, on the Growth plan and up). Give it:

* a **name** people see on the approval page;
* a **type**: **Confidential** for a server that can keep a client secret, or **Public** for a
  browser or desktop app that cannot (it relies on PKCE alone);
* its **redirect URIs**: `https` URLs, or `http://127.0.0.1` or `http://[::1]` for an app on the
  same computer. They are matched **exactly**: a trailing slash, a different path or an extra query
  is a different URI. The one exception is the port of a `127.0.0.1` or `[::1]` URI, which may be
  any port, so a desktop app can listen wherever it finds a free one;
* the **permissions** it may ask for.

You get a **client id** (`hq_app_…`, public) and, for a confidential app, a **client secret**
(`hq_ocs_…`), shown **once**. Roll the secret any time with an overlap of up to 7 days.

Deleting an app removes it from every organization that approved it: every approval and every token
of it stops at once, and its client id and secrets stop working. Each of those organizations sees the
removal in its audit log.

## Let members approve apps [#let-members-approve-apps]

Third-party apps are **off** in every organization until an owner or admin turns on **Let members
allow third-party apps** in **Settings**, **Developers**. Apps your own organization registered
always work. Turning it off stops every other organization's app at once, and they work again when
it is turned back on. Owners and admins see every member's apps there and can remove any of them.
Each person sees their own under **Profile**, **Apps**.

## The flow [#the-flow]

### 1. Send the person to HQ [#1-send-the-person-to-hq]

Make a PKCE pair: a random `code_verifier` (43 to 128 characters) and its
`code_challenge = BASE64URL(SHA256(code_verifier))`. Then redirect the browser to:

```text
https://hq.aiworkforceone.com/oauth/authorize
  ?response_type=code
  &client_id=hq_app_…
  &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
  &scope=teams%3Aread%20sessions%3Aread%20sessions%3Achat.read
  &state=…
  &code_challenge=…
  &code_challenge_method=S256
```

`state` is required (check it when the person comes back), and only `S256` is accepted. The person
signs in if needed, picks **one** organization, sees what the app will be able to do in plain words,
and chooses **Allow access** or **Deny**.

### 2. Handle the callback [#2-handle-the-callback]

HQ redirects to your `redirect_uri` with `code`, your `state` and `iss=https://api-hq.aiworkforceone.com`
(check `iss` too). On **Deny** it sends `error=access_denied`. A request HQ could not accept comes back
as `error=invalid_request`, `invalid_scope` or `unsupported_response_type`. An unknown client or an
unregistered redirect URI never redirects anywhere.

### 3. Exchange the code [#3-exchange-the-code]

The code lives **60 seconds** and works **once**.

```bash
curl -X POST https://api-hq.aiworkforceone.com/oauth/token \
  -u "hq_app_…:$HQ_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=hq_oac_… \
  -d redirect_uri=https://example.com/oauth/callback \
  -d code_verifier=…
```

A public app sends `client_id=hq_app_…` in the body instead of `-u`. The answer:

```json
{
  "access_token": "hq_oat_acme_…",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "hq_ort_acme_…",
  "scope": "teams:read sessions:read sessions:chat.read"
}
```

### 4. Call the API [#4-call-the-api]

Use the access token exactly like an API key:

```bash
curl https://api-hq.aiworkforceone.com/v1/me -H "Authorization: Bearer $HQ_ACCESS_TOKEN"
```

`GET /v1/me` answers `kind: "oauth"`, the app, the organization the person picked and the scopes.
Access tokens last **15 minutes**.

### 5. Refresh [#5-refresh]

```bash
curl -X POST https://api-hq.aiworkforceone.com/oauth/token \
  -u "hq_app_…:$HQ_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=hq_ort_acme_…
```

Every refresh returns a **new** refresh token; the old one is used up. You may pass a narrower
`scope`, never a wider one. A refresh token unused for 30 days stops working.

**Never use a refresh token twice.** HQ treats a used refresh token (or a code that already got
tokens) presented again as stolen: it revokes the whole chain of tokens **and** the approval, and
the person has to approve the app again. Store the new refresh token before you use the new access
token. A code whose exchange was refused (a wrong verifier, say) is simply used up: presenting it
again is `invalid_grant`, and the approval stays.

### Revoke [#revoke]

```bash
curl -X POST https://api-hq.aiworkforceone.com/oauth/revoke \
  -u "hq_app_…:$HQ_CLIENT_SECRET" \
  -d token=hq_ort_acme_…
```

Revoking either token ends the whole chain. The answer is always `200`, even for an unknown token.

## Discovery [#discovery]

`GET https://api-hq.aiworkforceone.com/.well-known/oauth-authorization-server` publishes the
endpoints, `S256`, the client authentication methods and every scope an app may ask for (RFC 8414).

## Errors [#errors]

The token and revoke endpoints answer the OAuth error shape, `{ "error", "error_description" }`:

| `error`                  | When                                                                                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_client`         | Wrong or missing client credentials, a secret sent for a public app, or a turned-off app (`401` with HTTP Basic)                                                     |
| `invalid_grant`          | The code or refresh token is wrong, expired, used, revoked, or for another app; the verifier or the redirect URI does not match; or the person is no longer a member |
| `invalid_scope`          | A refresh asked for more than the token had                                                                                                                          |
| `invalid_request`        | A parameter is missing, or the body is not a form                                                                                                                    |
| `unsupported_grant_type` | Anything but `authorization_code` or `refresh_token`                                                                                                                 |
| `slow_down` (`429`)      | Too many refused requests from your address or for your client id, or too many revocations for your client. Wait the `Retry-After` seconds                           |

On `/v1`, a token whose organization turned third-party apps off gets
[`third_party_apps_disabled`](/docs/api/errors/#third_party_apps_disabled); everything else is the same
as for a key, starting with [`invalid_credentials`](/docs/api/errors/#invalid_credentials).
