OAuth apps

An app that many organizations install, such as a Zendesk or Freshdesk marketplace app or a platform's integration, shouldn't ask each of them for an API key. With OAuth, an organization's admin approves the app on Spiiksi and the app gets its own token for that organization.

Register the app#

In API & integrations → OAuth apps, enter the app's name and its redirect URIs (https; http only on localhost). You get a client id (spk_app_…) and a client secret (spk_cs_…, shown once).

1. Send the admin to Spiiksi#

https://spiiksi.fi/oauth/authorize
  ?client_id=spk_app_…
  &redirect_uri=https://app.example.com/callback
  &scope=calls:write%20calls:read
  &state=<random, to check on return>
  &code_challenge=<BASE64URL(SHA256(verifier))>
  &code_challenge_method=S256

They sign in if needed, choose the organization (they must be its admin) and approve the scopes asked for. Without scope, the app asks for all of them.

2. Back at your redirect URI#

https://app.example.com/callback?code=…&state=…

Check state. If the admin refused: ?error=access_denied&state=….

3. Trade the code for tokens#

Within 10 minutes:

curl https://api.spiiksi.fi/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://app.example.com/callback \
  -d code_verifier=$VERIFIER

{"access_token": "spk_oat_…", "token_type": "Bearer", "expires_in": 3600,
 "refresh_token": "spk_ort_…", "scope": "calls:read calls:write", "org_id": "…"}

Keep org_id with the tokens: it is the organization the app now acts for. Apps that can't keep a secret (in a browser, on a device) leave the secret out and rely on the PKCE verifier.

4. Call the API#

curl https://api.spiiksi.fi/v1/calls -H "Authorization: Bearer spk_oat_…"

The token works like an API key with the granted scopes, for that organization, always in live mode.

Refresh#

An access token lasts an hour. Get new tokens with the refresh token; each refresh token works once, and the old access token stops working:

curl https://api.spiiksi.fi/oauth2/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token=spk_ort_…

Disconnect#

• POST /oauth2/revoke with token=… (either token) disconnects the app from that organization.
• Organizations see their connected apps under API & integrations and can disconnect them; the tokens stop at once.
• Deleting the app in your dashboard disconnects it everywhere.

Discovery metadata (RFC 8414): https://api.spiiksi.fi/.well-known/oauth-authorization-server.