Auth Code Grant Flow

📘

OAuth Application Required

In order to authorize with OAuth, you are required to create a Universe application.

Applications can be created here: https://www.universe.com/oauth/applications

Universe has built-in support for the OAuth 2.0 Auth Code Grant Flow.

All authorized requests in our API require you to implement this strategy or the client credentials flow. Most developers requesting access to Universe user data should use this flow. Before proceeding with this guide, please make sure that you have created a Universe OAuth Application. Additionally, please familiarize yourself with OAuth 2.0 concepts generally: http://oauthbible.com

Here is a quick demo which demonstrates how to get an access token at Universe in 1 minute:

Step 1. Get the User's Authorization

To begin the Authorization Code flow, your web application should first send the user to the authorization URL:

https://www.universe.com/oauth/authorize?response_type=code&scope=public&client_id=APPLICATION_ID&redirect_uri=CALLBACK_URL

Where:

• response_type: code – This must match the required value - specifying the type of authorization returned.
• scope: public – The scopes which you want to request authorization for. Right now, Universe supports only one scope.
• client_id: Application ID – Your application's Client ID. You were provided this by our developer support team.
• redirect_uri: Callback URL – Your URL to which Universe will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the code URL parameter. This URL must be registered with your application and must be served via HTTPS.

Optionally, you may also provide a state parameter. Per the OAuth spec, this value:

is used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

For example:

<a href="https://www.universe.com/oauth/authorize?response_type=code&scope=public&client_id=APPLICATION_ID&redirect_uri=CALLBACK_URL">
  Sign In With Universe
</a>

The purpose of this call is to obtain consent from the user to invoke the API to do certain things on behalf of the user. Universe will authenticate the user and obtain consent, unless consent has been previously given.

Once consent has been granted, we will redirect the user back to your redirect_uri with a query parameter of code - this is the auth code you need to exchange for an access token.

📘

Using State?

Note that if you are using the optional state param, we will echo it back at the redirect phase.

Step 2. Exchange the Authorization Code for an Access Token

Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to make authenticated requests to our API. Using the Authorization Code (code) from the previous step, you will need to POST to the Token URL:

export APPLICATION_ID=...
export APPLICATION_SECRET=...
export REDIRECT_URI=...
export AUTHORIZATION_CODE=...

curl --request POST \
  --url 'https://www.universe.com/oauth/token' \
  --header 'content-type: application/json' \
  --data "{\"grant_type\":\"authorization_code\", \"client_id\":\"$APPLICATION_ID\", \"client_secret\":\"$APPLICATION_SECRET\", \"redirect_uri\":\"$REDIRECT_URI\", \"code\":\"$AUTHORIZATION_CODE\"}"

Where:

• grant_type: This must be authorization_code.
• client_id: APPLICATION_ID – Your application's Client ID.
• client_secret: APPLICATION_SECRET – Your application's Client Secret.
• code: AUTHORIZATION_CODE – The Authorization Code received from the initial authorize call.
• redirect_uri: REDIRECT_URI – The URL must match exactly the redirect_uri passed to /authorize.

The response contains the access_token, refresh_token, expires_in, token_type, scope, and created_at values, for example:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "public",
  "created_at": 1494964915
}

Note that your access_token will be valid for the number of seconds specified by expires_in. Once the expiry time has passed, you will need to exchange the refresh_token for a new access_token.

❗️

Security Warning

It is important to understand that the Authorization Code flow should only be used in cases such as a Regular Web Application where the Client Secret can be safely stored. In cases such as a Single Page Application, the Client Secret is available to the client (in the web browser), so the integrity of the Client Secret cannot be maintained.

Step 3. Using the Access Token

Once the access_token has been obtained it can be used to make calls to the API by passing it as a Bearer Token in the Authorization header of the HTTP request:

curl --request GET \
  --url https://www.universe.com/some_endpoint \
  --header 'authorization: Bearer ACCESS_TOKEN'