Using the API with mobile or browser apps

The commercetools™ platform offers OAuth scopes and endpoints designed to enable a secure communication with the API from a mobile or browser app. This tutorial teaches you how you can use them. It will walk you through on how to display products, creating a customer account and putting a product into a cart.

To follow this tutorial, you should have a project set up, as described in Getting Started.

Why we can’t trust a mobile or browser app like a server

When we write a frontend that renders webpages on a server, we can trust that this code is secured from inspection, and that no man-in-the-middle attack can be performed because we control which certificates are trusted. However, when the code that communicates with the API runs on a mobile device or inside a browser, it is rather easy to inspect the code (and extract secrets, such as the OAuth client) or perform a man-in-the-middle attack (e.g. to steal an OAuth token).

While we give the frontend server far-reaching access to the data (e.g. it can access the orders of all customers), we trust it to use the API only appropriately (e.g. it will only render order data of the customer logged into the session). If we gave the same access to an app, there is a large risk that a hacker could access all of this data (e.g. the hacker could steal an OAuth token, and use it to access the order data of all customers).

Limiting access with OAuth scopes

To limit the access of an app to the data it can view or edit via the API, we can use OAuth scopes. The app should not be able to edit products, but it should display them. The view_products scope enables the app to retrieve products and related data (e.g. product types and categories), but not to edit that data.

There is some data we want to give the app access to only if it is asking for it on behalf of a customer: E.g. it should not have access to orders of all customers, but if a specific customer has logged in, it should be able to access her order data. We can use the OAuth password flow with the scopes manage_my_orders (for cart and order data) and manage_my_profile (for account-related data), along with the /me endpoints, for that.

Creating an OAuth client

First, we need to create an OAuth client with the permissions view_products, manage_my_orders and manage_my_profile. In the Admin Center, go to the “Developers” section and click on “API Clients”. Click “Add API client”, give it a name and either select the three permissions manually or use the shortcut at the bottom of the permission list. After you click “Create”, you can copy the client_id, client_secret and the scope (which contains the permissions you selected).

Creating a regular token with the Client Credentials Flow

If we don’t want to force the customer to immediately log in upon opening the app, we need to utilize the API without using the OAuth password flow. We use the OAuth client we just created to get a regular token with the three scopes we need.

$curl https://{client_id}:{client_secret}@auth.sphere.io/oauth/token -X POST -d "grant_type=client_credentials&scope=view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"

The response contains the token in the field access_token:

  "access_token": "vkFuQ6oTwj8_Ye4eiRSsqMeqLYNeQRJi",
  "token_type": "Bearer",
  "expires_in": 172800,
  "refresh_token": "OWStLG0eaeVs7Yx3-mHcn8iAZohBohCiJSDdK1UCJ9U",
  "scope": "view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"

This token can now be used to access products, e.g.:

$curl -sH "Authorization: Bearer vkFuQ6oTwj8_Ye4eiRSsqMeqLYNeQRJi" https://api.sphere.io/{projectKey}/product-projections?staged=true&limit=10

Creating a new Customer

Eventually, the customer will either need to log in or create a new account. The manage_my_profile scope authorizes the token to sign up a customer.

After we have collected important information like name, email and password from the customer, we can send her data to the API:

POST /{projectKey}/me/signup with:

  "firstName": "Alice",
  "lastName": "Doe",
  "email": "alice@example.org",
  "password": "secret"

The command could look like following:

$curl -sH "Authorization: Bearer {access_token}" -X POST -d '{"firstName": "Alice","lastName": "Doe","email": "alice1@example.org","password": "secret"}' https://api.sphere.io/{projectKey}/me/signup

Creating a token bound to a Customer with the Password Flow

Let’s create a Password Flow token for this customer (note that we use /oauth/{projectKey}/customers/token now):

$curl https://{client_id}:{client_secret}@auth.sphere.io/oauth/{projectKey}/customers/token -X POST -d "grant_type=password&username=alice@example.org&password=secret&scope=view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"

In addition to the regular access_token, this response also contains the refresh_token:

  "access_token": "v-dZ10ZCpvbGfwcFniXqfkAj0vq1yZVI",
  "expires_in": 172800,
  "scope": "view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}",
  "refresh_token": "OWStLG0eaeVs7Yx3-mHcn8iAZohBohCiJSDdK1UCJ9U",
  "token_type": "Bearer"

We can save the refresh token securely (e.g. on the mobile device) to get a new access token, without saving the email or password of the user.

$curl https://{client_id}:{client_secret}@auth.sphere.io/oauth/{projectKey}/customers/token -X POST -d "grant_type=refresh_token&refresh_token=OWStLG0eaeVs7Yx3-mHcn8iAZohBohCiJSDdK1UCJ9U"

Note that if the customer changes her password, access tokens and refresh tokens become invalid and your app has to ask the user for the new password to get new tokens.

Using a Password Flow token

Our password flow token can be used for the same requests as before, e.g. we can retrieve a list of products. But we can also access data specific to the customer we’ve logged in with. We don’t use the regular endpoints (such as /carts/), but the endpoints designed to be used with the password flow (such as /me/carts) instead.

For example, we can view her account data:

$curl -sH "Authorization: Bearer v-dZ10ZCpvbGfwcFniXqfkAj0vq1yZVI" https://api.sphere.io/{projectKey}/me

or view her carts:

$curl -sH "Authorization: Bearer v-dZ10ZCpvbGfwcFniXqfkAj0vq1yZVI" https://api.sphere.io/{projectKey}/me/carts

Writing with a Password Flow token

We also have write access to the data of the customer. For example, we can create a new cart:

POST /{projectKey}/me/carts with:

  "currency": "USD",
  "country": "US"

This looks very similar to the regular Create Cart, but there is a big difference: The cart will automatically belong to the customer we’ve logged in with, e.g. the customerId will be the ID of Alice.

We can now use this cart much like we’re using any other cart, e.g. we can add a line item:

POST /{projectKey}/me/carts/<cart-id> with:

  "version": <cart-version>,
  "actions": [{
    "action": "addLineItem",
    "productId": "<product-id>",
    "variantId": 1,
    "quantity": 1


You’ve seen how to get a regular token to view products without having to log in a customer, how to get a token with the password flow and how to use it with the /me endpoints. Now you can securely use the commercetools™ platform API from a mobile app or a browser application!

comments powered by Disqus