App credentials (OAuth 2.0)

The authorization-code flow for apps that sign your customers in to Shout About Us — they enter their password on our page, your server gets a token.

Use App credentials (OAuth 2.0) when other people sign in to your app: your users sign in with their Shout About Us email and password on our page (never in yours), and your server receives a token that acts as that user. Most partners calling the API as themselves don't need this — a Personal access token is simpler.

The token acts with the access level of the user behind it. It can also open the portal with no second sign-in (the rs-sso-login handoff). JumpCloud is separate — see JumpCloud SSO.

Before you start

Base URL: https://production-api.shoutaboutus.com
Portal: your portal URL (or your white label domain)

App credentials give you three things:

Item	What it is
`client_id`	Your app's public identifier. Safe to include in URLs.
`client_secret`	Your app's password. Shown only once when the credentials are created — store it somewhere safe, server-side only.
`redirect_uri`	The page on your app where users return after signing in, e.g. `https://yourapp.com/callback`. It must match exactly later — including https and any trailing slash.

Create your app credentials

Sign in to the dashboard and open the API Keys page.
Click Add credentials on the App credentials card, give your app a name, and enter your callback URL.
Copy the client_id and client_secret shown — the secret is displayed only this once. If you lose it, create new credentials and update your app.

The flow (four steps)

Step 1 — Send the user to our sign-in page. When the user clicks "Sign in with Shout About Us" in your app, open the authorize URL in their browser with your client_id, redirect_uri, response_type=code, scope=*, and a random state. Full details: Step 1: Send the user to sign in.

Step 2 — The user comes back with a code. After approving, the user lands on your redirect_uri with code and state. Check state matches step 1; the code is single-use and expires in ~10 minutes. Details: Step 2: Receive the code.

Step 3 — Swap the code for a token. From your server, POST /oauth/token (form-encoded, at the server root) with grant_type=authorization_code, your credentials, redirect_uri, and the code. You get an access_token (24 h) and a refresh_token (30 days). Details: Step 3: Exchange the code for a token.

Step 4 — Use the token. Add Authorization: Bearer <access-token> to each request (good first call: GET /api/v1/verify-token), or open the portal already signed in via the rs-sso-login handoff.

Keeping the session alive

Refresh: send grant_type=refresh_token with your refresh_token, client_id and client_secret to /oauth/token — no user interaction, valid for 30 days.
Sign out: Revoke a token cancels a token before it expires.

Checklist before going live

Your redirect_uri is registered and matches exactly what your app sends.
You check state on return (step 2) — it protects users against forged sign-ins.
Tokens live on your server only — never in page URLs or browser storage (except the one-time portal handoff link).
client_secret never appears in logs, error messages, or anything sent to the browser.

Troubleshooting

I lost my client_secret. Can I see it again? No — it's shown only once. Create new credentials and update your app.

invalid_scope error. Use scope=* — named scopes aren't supported.

Redirect URI invalid. The redirect_uri must match a saved callback URL character-for-character, including https:// and any trailing slash.

invalid_grant on token exchange. The code was already used or expired (~10 min), or the redirect_uri doesn't match step 1 — restart from step 1. A refresh fails this way when the refresh token has expired; ask the user to sign in again.

Which sign-in methods does an account support? Call Discover auth methods with the user's email.

Updated 4 days ago

Did this page help you?