AI Workforce OneHQDocs

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: 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

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=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

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" }:

errorWhen
invalid_clientWrong or missing client credentials, a secret sent for a public app, or a turned-off app (401 with HTTP Basic)
invalid_grantThe 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_scopeA refresh asked for more than the token had
invalid_requestA parameter is missing, or the body is not a form
unsupported_grant_typeAnything 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.