HTTP API - Authorization

Authorization methods and principles used to access the commercetools platform HTTP APIs.

OAuth2

The HTTP API authorization uses ↗ OAuth2 .

Clients must obtain an access token from the auth service using one of the authorization flows described below, before they are able to make authorized requests to other commercetools platform services. On successful completion of an authorization flow, a client will be given an access_token, which they need to include in requests to authorized service endpoints via the HTTP Authorization header like this:

Authorization: Bearer {access_token}

The access_token has a lifetime (in seconds) determined by the parameter expires_in.

Hosts

The OAuth2 APIs are currently provided at the following URLs depending on the region the project is hosted on:

  • Europe: https://auth.sphere.io/
  • United States: https://auth.commercetools.co/

Authorization Flows

Examples

We maintain a Git repository of code samples of how to authenticate to our API in various languages on ↗ Hello API Github repository .

Client Credentials Flow

To obtain an access token through the client credentials flow, simply issue the following request to the auth service, providing your client_id and client_secret via ↗ HTTP Basic Authentication , where the username is the client_id and the password is the client_secret:

POST https://{host}/oauth/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope={scope}

Example Request

$curl https://{host}/oauth/token -X POST \
	--basic --user "{clientId}:{clientSecret}" \
	-d "grant_type=client_credentials&scope=manage_project:{projectKey}"

Example Response

{
  "access_token": "vkFuQ6oTwj8_Ye4eiRSsqMeqLYNeQRJi",
  "expires_in": 172800, // seconds (2 days)
  "scope": "manage_project:{projectKey}",
  "token_type": "Bearer"
}

Parameters are provided using the application/x-www-form-urlencoded content type. The scope parameter is optional, but recommended.

Password Flow

To obtain an access token through the password flow, you need to provide the email and unencrypted password of the customer in addition to your OAuth client credentials.

POST https://{host}/oauth/{projectKey}/customers/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded
grant_type=password&username={email}&password={password}&scope={scope}

Example Request

$curl https://{host}/oauth/{projectKey}/customers/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=password&username=alice@example.org&password=secret&scope=view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}"

Example Response

{
  "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"
}

In addition to the access token, a refresh token is issued. The refresh token may be used to get a new access token without supplying email and password if the access token has expired.

Refresh Token Flow

To obtain an access token through the refresh token flow, you need to provide the OAuth client credentials as well as the refresh token.

POST https://{host}/oauth/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={token}

Refresh tokens expire 6 months after last usage. Therefore a refresh token that is regularly used will never expire.

Tokens for Anonymous Sessions

To obtain an access token for an Anonymous Session, the OAuth client needs the create_anonymous_token scope. The regular Client Credentials Flow is used.

These access tokens are similar to those issued with the Password Flow, but they are not associated with a customer but with an anonymousId. In addition to the access token, a refresh token is issued. The refresh token is the only way to get a new access token for this particular anonymousId.

The anonymousId is either generated by the API or an unused id may be supplied with the optional parameter anonymous_id.

POST https://{host}/oauth/{projectKey}/anonymous/token
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope={scope}&anonymous_id={id}

Example Request

$curl https://{host}/oauth/{projectKey}/anonymous/token -X POST \
    --basic --user "{clientId}:{clientSecret}" \
    -d "grant_type=client_credentials&scope=view_products:{projectKey} manage_my_orders:{projectKey} manage_my_profile:{projectKey}&anonymous_id={uniqueId}"

Example Response

{
  "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"
}

Managing token requests

For security reasons, we advise requesting tokens sparingly and keeping the number of active tokens to a minimum whenever possible.

We do not recommend requesting a token for every work item. If a client application requests too many tokens, it might be rate-limited.

We recommend getting new tokens when appropriate using automatic token management. Our SDK clients provide support for automatic token management, or you can implement token management yourself.

Short-lived applications

In some scenarios, your SDK clients are short-lived. For example, a script triggered by a cron job which creates a client every time the job runs, or a function in a serverless Function-as-a-Service environment.

We recommend the following approaches when working with short-lived client applications to reduce the number of tokens requested.

One approach is to store a token in the filesystem, a cache, or the application’s configuration. You can the refresh the token at a regular interval. In this approach, all instances of your application use the same token. In most of our SDKs, an existing token can be passed to the client. For example, in the following SDKs:

In a serverless FaaS environment, you should be able to use the global execution context to store your client across warm invocations (when the FaaS re-uses a function instance and it is not subject to a cold-start). Here is an example for an AWS Lambda function that uses the execution context.

Scopes

All OAuth 2.0 clients and access tokens have a scope. The scope constrains the endpoints to which a client has access, and whether a client has read or write access to an endpoint. Scopes are defined in the Merchant Center for a single project when creating an API client. Once you create an API client, you cannot redefine the scopes.

When creating a client or requesting an access token, specify only the scopes your application needs. When requesting an OAuth 2.0 access token, the scope parameter may be omitted. If you do not provide a scope, the access token is granted all the scopes defined for the API client.

manage_project:{projectKey}
Grants full access to the all APIs for the project, with the exception of the API clients endpoints. For production use, do not use manage_project. Instead, create an API client and specify only scopes your application needs. An API client using the manage_project scope cannot request a token with less scopes.

manage_products:{projectKey}
Grants access to all the APIs related to creating, modifying and viewing products in a project. Implies the view_products scope.

view_products:{projectKey}
Grants access to all the APIs related to viewing products in a project.

manage_orders:{projectKey}
Grants access to all the APIs related to creating, modifying and viewing orders, carts, shipping in a project. Implies the view_orders scope.

view_orders:{projectKey}
Grants access to all the APIs related to viewing orders, carts, shipping in a project.

manage_my_orders:{projectKey}
When used as a scope in the password flow, grants access to APIs for creating, modifying and viewing orders and carts of the customer for whom the access token was issued. When used as a scope to generate an access token for an anonymous session, grants access to the orders and carts of an anonymousId. Also grants access to the APIs for viewing shipping methods.

manage_shopping_lists:{projectKey}
Grants access to all the APIs related to creating, modifying and viewing shopping lists in a project. Implies the view_shopping_lists scope.

manage_my_shopping_lists:{projectKey}
When used as a scope in the password flow, grants access to APIs for creating, modifying and viewing shopping lists of the customer to whom the access token was issued. When used as a scope to generate an access token for an anonymous session, grants access to the shopping lists of an anonymousId.

view_shopping_lists:{projectKey}
Grants access to all the APIs related to viewing shopping lists in a project.

manage_customers:{projectKey}
Grants access to all the APIs related to creating, modifying and customers and in a project. Implies the view_customers scope.

view_customers:{projectKey}
Grants access to all the APIs related to viewing customers in a project.

manage_my_profile:{projectKey}
When used as a scope in the password flow, grants access to the APIs for creating, modifying and viewing the profile of a specific customer for whom the access token was issued. When used as a scope to generate an access token for an anonymous session, grants access to sign up and sign in.

manage_types:{projectKey}
Grants access to all the APIs related to creating, modifying and viewing types in a project. Implies the view_types scope.

view_types:{projectKey}
Grants access to all the APIs related to viewing types in a project.

manage_payments:{projectKey}
Grants access to all the APIs related creating, modifying and viewing payments in a project.

manage_my_payments:{projectKey}
When used as a scope in the password flow, grants access to the APIs for creating, modifying and viewing payments of the customer for whom the access token was issued. When used as a scope to generate an access token for an anonymous session, grants access for the payments of the anonymousId for which the access token was issued.

view_payments:{projectKey}
Grants access to all the APIs related to viewing payments in a project.

create_anonymous_token:{projectKey}
Grants access to access tokens for Anonymous Sessions.

manage_subscriptions:{projectKey}
Grants access to all the APIs related to creating, modifying and viewing subscriptions in a project.

manage_extensions:{projectKey}
Grants access all the APIs related to creating, modifying and viewing API extensions in a project.

manage_project_settings:{projectKey}
Grants access to all the APIs related to modifying and viewing project settings in a project.

view_project_settings:{projectKey}
Grants access to all the APIs related to viewing project settings.

manage_states:{projectKey}
Grants access to all the APIs related to creating, modifying and viewing states in a project.

view_states:{projectKey}
Grants access to all the APIs related to viewing states in a project.

view_messages:{projectKey}
Grants access to all the APIs related to viewing messages in a project.

manage_api_clients:{projectKey} Grants access to the APIs for creating, deleting and viewing API clients.

view_api_clients:{projectKey} Grants access to the APIs for viewing API clients.

introspect_oauth_tokens:{projectKey} Grants access to introspect tokens issued to other clients.

OAuth2 Token Introspection

The auth service also implements ↗ OAuth2 Token Introspection available under /oauth/introspect. It allows to determine the active state of an OAuth 2.0 access token and to determine meta-information about this access token, such as the scope.

Like the other endpoints, it is protected by client authentication. A client can always introspect its own access tokens. A client with introspect_oauth_tokens:{projectKey} permission (also implied by manage_project) can introspect any access token in that project, even if it was issued to a different client. If the requesting client does not have permission to introspect the given token, it is treated as not active and no further information is returned.

Example Request

$curl https://{host}/oauth/introspect -X POST \
        --basic --user "{clientId}:{clientSecret}" \
        -d "token=nbzLp_xTvAmPJnilFuZGaiukILpuaCxQ"

Example Response (Active)

{
  "active": true,
  "scope": "view_products:background-test-26",
  "exp": 1501158800852
}

Example Response (Inactive)

{
  "active": false
}

If active is true, the access token can currently be used with the API, within the scope. The exp timestamp indicates when this token will expire.

You may cache the result, but consider that a token can not only expire, but also be revoked earlier (e.g. if the client that issued the token is deleted). The RFC 7662, Section 4 summarizes the tradeoff in the second-last paragraph.