Universe Public API

The Universe Developer Hub

Welcome to the Universe developer hub. You'll find comprehensive guides and documentation to help you start working with Universe as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Auth Code Grant Flow

OAuth Application Required

In order to authorize with OAuth, you are required to create a Universe application. During the initial launch of our API, you must do so by requesting one from developers@universe.com.

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

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&
    client_id=CLIENT_ID&
    redirect_uri=https://REDIRECT_URI&
    scope=public

Where:

  • response_type: This must match the required value code - specifying the type of authorization returned
  • client_id: Your application's Client ID. You were provided this by our developer support team.
  • redirect_uri: The 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.
  • scope: The scopes which you want to request authorization for. Right now, Universe supports one scope, public.

For example:

<a href="https://www.universe.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://REDIRECT_URI&scope=public">
  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.

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:

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

Where:

  • grant_type: This must be authorization_code.
  • client_id: Your application's Client ID.
  • client_secret: Your application's Client Secret.
  • code: The Authorization Code received from the initial authorize call.
  • 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://api.universe.com/some_endpoint \
  --header 'authorization: Bearer ACCESS_TOKEN'

Auth Code Grant Flow