Authentication

This document provides details on the necessary steps and information to get started with an API integration to StockX. It includes information on API keys, authentication flow, as well as technical information, and examples.

How OAuth2 Authorization Works

StockX uses the OAuth2 Authorization Code flow to authenticate and authorize user requests. In order for your application to access StockX Public APIs and your data within StockX, your application will need to integrate with the Authorization Code Flow to gain access.

Access

StockX Audience: Used to access StockX API services. To access any StockX API service, such as login or bid, please make sure your audience is set to gateway.stockx.com.

Auth Domain: To access the StockX auth service, the domain for authentication endpoints is https://accounts.stockx.com.

Scope: A valid OpenID Connect (OIDC) scope is used by StockX auth service to give the API User application the correct access level. The scope sent must contain at least opened, required by OIDC to verify the user’s identity and required to receive a refresh token; a minimal necessary scope to access StockX is scope=offline_access openid

Authenticating at StockX as an API User

Authorize the user

First you must authorize the application and the user via the StockX IDP. This is done by sending the user to the /authorize endpoint URL with the proper credentials and grant.

For this first authorize call, the response type will be code. State is an opaque value that will be defined by the API User, e.g., state = abcXYZ9876.

GET https://accounts.stockx.com/authorize?
    response_type=code&
    client_id={APPLICATION_ID}&
    redirect_uri={APPLICATION_REDIRECT_URI}&
    scope=offline_access%20openid&
    audience=gateway.stockx.com&
    state={OPAQUE_STATE_VALUE}

Parameter Name	Required Value	Description
response_type	code	Denotes the kind of credential returned (`code` or `token`). For this flow, the value must be `code`.
client_id	Provided on the Keys page	Your application's Client ID, will be generated after application creation.
redirect_uri	Example: https://www.yourdomain.com/callback	The URL to which StockX auth service will redirect the browser after the authorization has been granted by the user. The Authorization Code will be available in the `code` URL parameter. You will need to provide this url in your application.
scope	`offline_access openid` (space as delimiter)	Specifies the scopes for which you want to request authorization, which dictate which claims (or user attributes) you want returned. In StockX is `scope=offline_access openid`
audience	gateway.stockx.com	The unique identifier of the API your web app wants to access. This is provided by StockX.
state	Any string API user chooses Example: abcXYZ9876	An opaque arbitrary alphanumeric string your app adds to the initial request that StockX auth service includes when redirecting back to your application. We recommend API users to use this string to validate the incoming callback request, to prevent cross-site request forgery (CSRF) attacks, which refer to https://owasp.org/www-community/attacks/csrf.

Login and receive authorization code

After successfully authorizing your application, the StockX login page will be shown and you must enter the email and password of the API User account. Once login is completed successfully, the response will be a HTTP 302 redirect with a URL. The authorization code is located at the end of the callback URI.

HTTP/1.1 302 Found
Location: undefined?code=AUTHORIZATION_CODE&state=xyzABC123

The code=AUTHORIZATION_CODE value in the URL, specifically the AUTHORIZATION_CODE value, is the value that you need. You will use that code on the next step to get tokens.

Note: This is your application’s endpoint that you will need to implement to receive the authorization code.

Exchange authorization code for a set of tokens

Now that you have received an Authorization Code, you must POST a new call to /authorize to exchange the code for tokens and add the extracted Authorization Code (code) from the previous step to the request.

Below you will find an example of a call to /authorize for token exchanging. Keep in mind that the response will give you a set of tokens and that some of them must be stored on your side securely as they will be needed later on to access StockX APIs.

Request

curl --request POST \
 --url 'https://accounts.stockx.com/oauth/token' \
 --header 'content-type: application/x-www-form-urlencoded' \
 --data 'grant_type=authorization_code' \
 --data 'client_id={YOUR_CLIENT_ID}' \
 --data 'client_secret={YOUR_CLIENT_SECRET}' \
 --data 'code={YOUR_AUTHORIZATION_CODE}' \
 --data 'redirect_uri={YOUR_CALLBACK_URI}'

Parameter Name	Description
grant_type	Set this to `authorization_code`
client_id	Generated at application creation
client_secret	Generated at application creation
code	The `authorization_code` retrieved in step 2
redirect_uri	The URL to which StockX auth service will redirect the browser after authorization has been granted by the user. The `authorization_code` will be available in the code URL parameter.

Response

If you are able to successfully exchange the code for tokens, you will receive a response with a payload containing access_token, refresh_token, id_token , and token_type. Please see below an example payload response.

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer"
}

Application Settings

The following guide shows how to create, update and delete a new application. The app provides the Client ID and Client Secret needed to implement authorization flows.

Note: At this time StockX supports one Application per StockX account

To do so, go to your Applications and click on the Create an App button to open the following dialog box:

Create an app

Enter your application's name, description, and callback URI of your choosing, and click CREATE. Your application is now created and registered, and you’ll see your newly created application on the Applications page.

The callback URI enables the StockX authentication service to automatically invoke your application every time the user logs in.

Application Page

Pauls app

The Applications page provides the following information:

Application name
Application description
Callback URI
A link to view your application credentials

Client ID, the unique identifier of your application
Client Secret, the key you will use to authorize your Web API calls

You can update your application by clicking the EDIT button, and you can delete the application by clicking the red DELETE button.

Call StockX API

Once you have obtained an access_token from the previous steps, you can start making API calls. The access token must be added to your header request as a bearer token, i.e., with the text Bearer in front.

The Production API URL: api.stockx.com

Authorization: Bearer {ACCESS_TOKEN}

x-api-key: {api-key}

A CURL example is shown below of a header with a bearer token

curl --location --request GET
'https://{baseUrl}/{version}/{endpoint} \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {api-key}'

Header Name	Description
baseUrl	StockX API URL, e.g. api.stockx.com
version	StockX API version, e.g. v1
authorization	Set this to `Bearer `access_token`
x-api-key	Auto-generated after developer access approval, located in the keys page

Note: Please note that the access_token has an expiration of 12 hours after which you need to request a new access_token, which you can do with the refresh_token step, outlined below.

Refresh Token

As a StockX API User once a call is made to the StockX audience with a bearer token, that token is verified. If the access_token is no longer valid, it will return you an HTTP 401 and you will need to renew your access_token.

To renew an access_token you need a refresh_token. refresh_token is a special token used by the IDP (Identity Provider) to allow you to request a new access_token when the one you received during authentication is no longer valid. A refresh_token is returned after a login and has a long lifespan, and it will be valid to exchange tokens for as long as your session is valid, so when you call to exchange tokens you will receive a new access_token but not a new refresh_token, as those are long-lived with your session.

In order to get a refresh token you must call /oauth/token with grant_type=refresh_token. To exchange a refresh token for an access token you must make the same call. The calls can only be made after you already made the /authorize call. A sample request and response to exchange a refresh_token or a new access_token is shown below:

curl --location --request POST \
 --url 'https://accounts.stockx.com/oauth/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=refresh_token' \
 --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
 --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
 --data-urlencode 'audience=gateway.stockx.com' \
 --data-urlencode 'refresh_token={YOUR_REFRESH_TOKEN}'

Parameter Name	Description
grant_type	Set this to `refresh_token`
client_id	Generated at application creation
client_secret	Generated at application creation
audience	Set this to `gateway.stockx.com`
refresh_token	The Refresh Token

{
  "access_token": "ey....",
  "expires_in": 43200,
  "id_token": "ey....",
  "scope": "openid email offline_access",
  "token_type": "Bearer"
}

Auth0 SDKs and Documentation

Please review the documentation below for our identity provider - Auth0.

Auth0 Authentication flow:

Auth0 PHP SDK and Documentation:

Auth0 Python Documentation:

Auth0 node documentation:

Example Code Snippet

The following code snippet simulates logging into StockX via Auth0, receiving an authorization code, and exchanging that code for an access token that can then be used in follow-up API calls. This code snippet is an example and is not meant for production.

"use strict";

/*
 * Do not commit your client ID, secret, or domain to your codebase. These
 * are here for the sake of convenience and should never be in your
 * version control system.
 * */

const AUTH0_CLIENT_ID = "";
const AUTH0_DOMAIN = "";
const AUTH0_CLIENT_SECRET = "";

/*
 * This callback URL is where you will be redirected to after you have
 * logged in. This is the URL you provided to StockX.
 * */

const CALLBACK_URL = "";

/* This redirect URI is where you will be redirected to after the
 * authorization code exchange for the access token.
 * */

const REDIRECT_URI = "";

/*
 * The unique identifier of the API your web app wants to access. This is provided by StockX.
*/
const AUTH0_AUDIENCE = "urn:gateway.stockx.com";

const GRANT_TYPE = "authorization_code";
const ACCESS_TOKEN_URL = `https://${AUTH0_DOMAIN}/oauth/token`;

const PORT = 8000;

const Auth0Strategy = require("passport-auth0");
const axios = require("axios");
const express = require("express");
const expressSession = require("express-session");
const passport = require("passport");

const session = {
    /*
     * This secret isn’t used by Auth0, but rather by the Express session.
     * It signs the session cookie ID.
     * */
    secret: "SESSION COOKIE ID SIGNER: ADD YOUR OWN",
    cookie: {},
    resave: false,
    saveUninitialized: false,
};

const app = express();

app.use(expressSession(session));

const strategy = new Auth0Strategy(
    {
        domain: AUTH0_DOMAIN,
        clientID: AUTH0_CLIENT_ID,
        clientSecret: AUTH0_CLIENT_SECRET,
        callbackURL: CALLBACK_URL,
    },
    (_, __, ___, profile, done) => done(null, profile)
);

passport.use(strategy);
app.use(passport.initialize());
app.use(passport.session());

const router = express.Router();
const authMiddleware = passport.authenticate("auth0", { scope: "openid email profile", audience: AUTH0_AUDIENCE });

router.get("/login", authMiddleware, (_, res) => res.redirect("/"));

/*
 * This is where the magic happens. When Auth0 redirects you to the
 * callback, it does so with an authorization code. That authorization code
 * can be exchanged for an access token. The access token is what you will
 * use to gain access to StockX's public API.
 * */

router.get("/callback", async (req, res) => {
    try {
        const { data } = await axios.post(ACCESS_TOKEN_URL, {
            grant_type: GRANT_TYPE,
            client_id: AUTH0_CLIENT_ID,
            client_secret: AUTH0_CLIENT_SECRET,
            redirect_uri: REDIRECT_URI,
            code: req.query.code,
        });

        return res.status(200).json(data);
    } catch (err) {
        return res.send(err.toString()).status(500);
    }
});

router.get("/", (_, res) =>
    res.send("Sample homepage. To login, navigate your browser to localhost:8000/login.").status(200)
);

app.use("/", router);

app.listen(PORT, () => {
    console.log(`Listening to requests on http://localhost:${PORT}`);
});