Authorization Code Grant

See Section 4.1 of Draft 16. This flow is suitable for applications which can make cross-domain HTTP requests, such as web, mobile, or desktop applications.

Obtaining an Authorization Code

To initiate the OAuth authorization delegation flow you must first direct your users to the Socialcast Authorization dialog where they can give your application permissions to access their Socialcast data and act on their behalf. Do this by opening the authorization dialog URL in a user-agent:

https://ENDPOINT_DOMAIN/oauth2/authorization?response_type=code&redirect_uri=CALLBACK_URL&client_id=CLIENT_ID

Embedded user agents seeking a more streamlined experience may skip the first step of the authorization flow by opening the following URL instead:

https://ENDPOINT_DOMAIN/oauth2/authorization/new?response_type=code&redirect_uri=CALLBACK_URL&client_id=CLIENT_ID

The following variables should be substituted:

The Socialcast server will handle authenticating the user and present them with the opportunity to approve or deny your access request. Once the user has made their choice, they will be redirected back to your application via the "redirect_uri" you supplied when sending the user to the Authorization dialog.

Authorization Granted Response

If the user chooses to grant your request, the Socialcast server will append the following parameters to the supplied redirect_uri before issuing the redirect to the user agent:

Access Denied or Error Responses

If some kind of error occurs before authorization has been granted, or the user choses not to authorize your application the server will append the following parameters to the supplied redirect_uri before issuing the redirect to the user agent:

Obtaining Access: Redeeming an Authorization Code

You can redeem an Authorization Code using the token endpoint by making a HTTP POST request to the token endpoint, located at:

https://COMMUNITY_DOMAIN/oauth2/token

supplying the following required parameters:

and using the client_id as the username and the client_secret as password for HTTP Basic Authentication:

Authorization: Basic ENCODED_CLIENT_CREDENTIALS

For example, your request would take the following form:

POST /oauth2/token HTTP/1.1
Host: COMMUNITY
Authorization: Basic ENCODED_CLIENT_CREDENTIALS
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI

Alternatively you can pass client_id and client_secret as POST parameters:

POST /oauth2/token HTTP/1.1
Host: COMMUNITY
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

Note that it is not acceptable to pass client credentials in a Basic Authorization and as POST parameters in the same request. Doing so will result in an invalid request error.

Successful Response

If redemption was successful, the Socialcast server will respond with an HTTP 200 with the response body is set to a JSON object containing information regarding your access refresh tokens:

For example:

{
access_token: 12341234,
token_type: "bearer",
expires_in: 3600,
refresh_token: 54325421
}

Error Response

If redemption was unsuccessful, the Socialcast server will respond with an HTTP 400 with the response body set to a JSON object containing information regarding the error that occurred while attempting to redeem the token:

For example:

{
error: "invalid_grant",
error_description: "The supplied authorization code has expired, please re-authorize this application."
}