Step 2: Receive the code

Overview

After the user approves or denies your app in Step 1, their browser returns to your redirect_uri with the result in the query string. This request arrives at your server; there is no Shout About Us endpoint to call in this step.

Check that state matches the value you stored, then pass the code to Step 3 straight away. The code works once and expires after 10 minutes.

Prerequisites

Step 1: Send the user to sign in, with the state you sent kept in the user's session.

Base URL

Your own app. This is the redirect_uri you registered, for example https://yourapp.com/callback.

Endpoint

GET <your redirect_uri>

Authentication

Public (no token)

No token is involved. Check state to confirm the request belongs to a sign-in you started; if it doesn't match, stop and discard the code.

Rate limit

Not applicable. This request is to your server.

Request parameters

On approval:

Parameter	In	Type	Required	Description
`code`	query	string	Yes	One-time authorization code. Exchange it within 10 minutes in Step 3.
`state`	query	string	Yes, if you sent one	The `state` you sent in Step 1, unchanged.

On an error:

Parameter	In	Type	Required	Description
`error`	query	string	Yes	`access_denied` (the user declined), `invalid_scope`, `login_required` or `consent_required` (with `prompt=none`).
`error_description`	query	string	Yes	A readable description.
`hint`	query	string	No	Extra detail, for example `The user denied the request`.
`state`	query	string	Yes, if you sent one	The `state` you sent in Step 1.

Request body

None.

Request payload

None.

Response body

Your app decides what to show the user.

Response payload

None.

Examples

Success payload

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

Error payload

The user declined:

https://yourapp.com/callback?state=RANDOM_STRING&error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&hint=The+user+denied+the+request

Result	Meaning
`code` present	Approved. Exchange the code in Step 3.
`error=access_denied`	The user declined. Start again from Step 1 if they want to retry.
`error=invalid_scope`	Step 1 sent a `scope` other than `*`. Leave `scope` out.
`error=login_required` / `consent_required`	Step 1 used `prompt=none`, but the user wasn't signed in or hadn't approved your app yet.

Example request

Your browser-facing route receives:

GET /callback?code=<authorization-code>&state=RANDOM_STRING HTTP/1.1
Host: yourapp.com

Updated 19 days ago

Did this page help you?