Authentication

OAuth 2 flow

At topi, we use OAuth 2 to secure and authenticate requests to our API. To authenticate with topi, you need to use Client Credentials grant_type flow. You need a client_id and a client_secret to authenticate with topi API. Make sure to talk to your topi representative to provide them for you.

We recommend using a mature OAuth 2 library in your preferred language for easier integration. OAuth 2 libraries manages token fetching and refreshing it after expiry.

You might notice that we use the same identity server for our sandbox and live environments. You will have a separate set of OAuth 2 client credentials for each environment. Tokens generated with sandbox OAuth client credentials will be invalid in live, and viceversa.

Obtaining your token

We show you how to obtain a topi token using plain HTTP (we recommend using a mature OAuth 2 library for that).

POST /oauth2/token
Authorization: Basic $BASE64_ENCODE(CLIENT_ID:CLIENT_SECRET)
application/x-www-form-urlencoded

grant_type=client_credentials&scope=client

Example using curl

curl -u $CLIENT_ID:$CLIENT_SECRET \
 -d'grant_type=client_credentials&scope=client' \
 'https://identity.topi.eu/oauth2/token'

Example using Javascript (Node.js, deno or Web Browser)

try {
  const resp = await fetch(new URL('https://identity.topi.eu/oauth2/token'), {
    method: "POST",
    headers: {
      "Authorization": `Basic ${btoa(`${clientId}:${clientSecret}`)}`,
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: "grant_type=client_credentials&scope=client"
  });

  const tokenInfo = await resp.json();
  console.log(tokenInfo)
} catch (e) {
  console.error(e)
}

Response is in JSON:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsImtpZCI6ImxvY2FsS2V5SU...(truncated)",
  "expires_in": 7200,
  "scope": "seller-catalog:read seller-catalog:edit seller-metrics:read seller-offer:read seller-offer:edit seller-order:read seller-order:edit seller-shipping-method:edit seller-shipping-method:read seller-shipment:edit seller-metrics:read user-info:read",
  "token_type": "Bearer"
}

Key	Value
access_token	(string) format: JSON Web Token (JWT)
token_type	(string) Bearer
expires_in	(number) number of seconds for the token until it expires, default to 2 hours
scope	(string) A space-separated string contains list of permissions granted to the token

If an error happen, topi API will return a 401 Unauthorized HTTP response with the following JSON body:

{
 "error": "invalid_client",
 "error_description": "Client authentication failed",
}

Key	Value
error	(string) Error code: invalid_client
error_description	(string) Description for the error happened

The token can be used by as many as end-users are there. And it should be stored securely on your backend. This means, that it is better to make all requests to topi via the backend, not via a web browser.

Authenticating your requests

After getting the token, all requests to topi must include the token as part of the Authorization header with type Bearer.

Authorization: Bearer $ACCESS_TOKEN

Example using curl

curl -H'Authorization: Bearer ACCESS_TOKEN' 'https://seller-api.topi.eu/v1/shipping-method'

---

Now that you understand how to authenticate with the API, you're ready to start your integration. We'll go step by step, beginning with syncing your catalog.