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.

We have two environments — Production and a testing environment called Sandbox. Each environment has its own set of OAuth 2.0 client credentials. Tokens generated using Sandbox credentials will not be valid in Production, and vice versa. For more details on the Sandbox authentication process, please refer to the documentation.

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.