Connected apps

Send the user to the authorize screen. An org admin reviews the requested scopes and approves; Telos redirects back to your redirect_uri with a one-time code and your state. PKCE (S256) is required for public clients and recommended for all.

https://www.telos-app.com/oauth/authorize
  ?client_id=app_…
  &redirect_uri=https://your-app.example.com/callback
  &response_type=code
  &scope=opportunity:read%20task:read%20insight:create
  &state=<opaque-csrf-token>
  &code_challenge=<base64url-sha256(verifier)>
  &code_challenge_method=S256

Exchange the code at the token endpoint. Public clients prove possession with the PKCE code_verifier; confidential clients send their client_secret. The endpoint speaks RFC 6749 form-encoding and returns RFC 6749 shapes — not the /api/v1 envelope.

curl -X POST 'https://www.telos-app.com/api/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=authorization_code \
  -d client_id=app_… \
  -d code=<authorization-code> \
  -d redirect_uri=https://your-app.example.com/callback \
  -d code_verifier=<pkce-verifier>          # public clients
  # -d client_secret=<secret>               # confidential clients

{
  "access_token": "telos_oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…"
}

Access tokens are short-lived (expires_in seconds). Trade the refresh token for a new pair; refresh tokens rotate on use, so store the latest one each time.

curl -X POST 'https://www.telos-app.com/api/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=refresh_token \
  -d client_id=app_… \
  -d refresh_token=<refresh-token>

Apps are registered in-product under Configurations → Connected accounts by an org admin (the oauth_app:manage capability). You set the app name, one or more redirect_uris, the allowed scopes, and the client type: confidential (server-side, issued a secret you can rotate) or public(SPA/native, PKCE only, no secret). A granted token can never exceed the app's allowed scopes, and is re-intersected with the granting user's live permissions on every call — if that user is demoted or deactivated, the token shrinks or dies with them.

Scopes are capability strings of the form resource:action. A token's scopes are its entire permission set. The full vocabulary (96 capabilities) is below; the ones marked admin can never be granted to an app or API key, only held by a signed-in user.