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 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
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:
httpsURLs, orhttp://127.0.0.1orhttp://[::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 a127.0.0.1or[::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
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
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:
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=S256state 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
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
The code lives 60 seconds and works once.
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:
{
"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
Use the access token exactly like an API key:
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
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
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
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
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; everything else is the same
as for a key, starting with invalid_credentials.