HTTP API - Authorization

The following is a description of authorization methods and principles used to access the commercetools platform HTTP APIs.

OAuth2

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:

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?grant_type=client_credentials&scope={scope}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The client_id and client_secret can also be encoded into the URL:

POST https://{clientId}:{clientSecret}@{host}/oauth/token?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"
}

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?grant_type=password&username={email}&password={password}&scope={scope}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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?grant_type=refresh_token&refresh_token={token}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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?grant_type=client_credentials&scope={scope}&anonymous_id={id}
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Scopes

All OAuth clients and access tokens are constrained to a scope (a set of permissions).

When creating an OAuth client or requesting an access token, we recommend that you specify only those scopes your application really needs, but not more. When requesting an access token, the scope parameter may be omitted. In absence of the scope parameter all the scopes defined for the API client will be granted.

The project scopes provide API access in the context of a specific project. Your client can only acquire those scopes which have been previously granted by a sufficiently authorized user through the Admin Center.

manage_project:{projectKey}
Grants full access to the APIs for the specified project.

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

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

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

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

manage_my_orders:{projectKey}
If used with the password flow, grants access to the APIs for creating, modifying and viewing orders and carts of the customer to whom the access token was issued. If used with the tokens for anonymous sessions, the access is granted for the orders and carts of the anonymousId to which the access token was issued. Also grants access to the APIs for viewing shipping methods.

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

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

manage_customers:{projectKey}
Grants access to the APIs for creating, modifying and viewing anything related to customers in a project. Implies view_customers for the same project.

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

manage_my_profile:{projectKey}
If used with the password flow, grants access to the APIs for creating, modifying and viewing the profile of the customer to whom the access token was issued. If used with the tokens for anonymous sessions, grants access to sign up and sign in.

manage_types:{projectKey}
Grants access to the APIs for creating, modifying and viewing anything related to types in a project.

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

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

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

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

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

view_project_settings:{projectKey}
Grants access to the API for viewing the project settings.

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

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

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