Step 1: Send the user to sign in

Overview

Start the OAuth 2.0 authorization-code flow by sending the user's browser to the Shout About Us sign-in page. The user signs in with their Shout About Us email and password on our page, then approves your app.

When they approve, we redirect the browser to your redirect_uri with a one-time code, which your server exchanges for a token in Step 3. This is a browser navigation, not an API call your server makes.

Prerequisites

App credentials: a client_id and at least one registered redirect URL, created on the API Keys page of the dashboard. See App credentials (OAuth 2.0).
A random state value you've stored in the user's session.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /oauth/authorize

This path is at the server root, not under /api/v1.

Authentication

Public (no token)

The user authenticates on our sign-in page. If they aren't signed in yet, the browser is redirected to it first and then comes back to the approval screen.
The sign-in page rejects accounts that must use single sign-on ("This account must sign in via SSO."), locked accounts, and platform administrator accounts.
The first time a user authorizes your app, they see an approval screen. Approval can't be skipped for any app.

Rate limit

This endpoint has no rate limit. Responses do not include X-RateLimit-* headers.

📘
The sign-in form this page redirects to (POST /oauth/login) is limited to 10 requests per minute per IP address, and it locks an account after repeated failed passwords.

Request parameters

Parameter	In	Type	Required	Description
`client_id`	query	string	Yes	Your app's client ID.
`redirect_uri`	query	string	Conditional	Where to send the user afterwards. It must match one of your registered redirect URLs exactly. Required when your app has more than one registered URL; send it every time so the value is explicit.
`response_type`	query	string	Yes	Always `code`.
`state`	query	string	Recommended	A random value. We return it unchanged in Step 2 so you can confirm the response belongs to a request you started. The server doesn't require it.
`scope`	query	string	No	Leave it out. Named scopes aren't defined; any value other than `` returns `invalid_scope`, and `` has no effect on this flow.
`code_challenge`	query	string	No	PKCE challenge. Optional, because app credentials from the dashboard are confidential clients. If you send it, send `code_verifier` in Step 3.
`code_challenge_method`	query	string	No	`S256` or `plain`. Defaults to `plain` when a `code_challenge` is sent.
`prompt`	query	string	No	`login` forces the user to sign in again, `consent` forces the approval screen, and `none` fails with `login_required` or `consent_required` instead of showing either.

Request body

None.

Request payload

None.

Response body

None. The response is an HTML sign-in or approval page, then a 302 redirect to your redirect_uri.

Response payload

After the user approves, the browser is redirected to:

https://yourapp.com/callback?code=<authorization-code>&state=RANDOM_STRING

See Step 2: Receive the code for what to do next.

Examples

Success payload

See Response payload.

Error payload

Errors about the app itself come back as JSON, because we can't safely redirect to an unverified URL.

400 Missing client_id

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
  "hint": "Check the `client_id` parameter"
}

401 Unknown client or redirect URL

Returned when the client_id doesn't exist, or redirect_uri doesn't match a registered URL.

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Other errors are sent to your redirect_uri as query parameters (error, error_description, hint, state) and are covered in Step 2: invalid_scope, access_denied, login_required and consent_required.

Status	Meaning
`302`	Redirect to the sign-in page, or to your `redirect_uri` with a `code` or an `error`.
`400`	`client_id` is missing, or a PKCE parameter is invalid.
`401`	The client is unknown, or `redirect_uri` doesn't match a registered URL.
`500`	Unexpected server error.

Example request

https://production-api.shoutaboutus.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&state=RANDOM_STRING

Open this URL in the user's browser. Don't call it from your server.