HTTP API - Authorization
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}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"
}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 Merchant 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.
manage_my_shopping_lists:{projectKey}
If used with the password flow, grants access to the APIs for creating, modifying and viewing shopping lists of the customer to whom the access token was issued.
If used with the tokens for anonymous sessions, the access is granted for the shopping lists of the anonymousId to which the access token was issued.
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.
manage_my_payments:{projectKey}
If used with the password flow, grants access to the APIs for creating, modifying and viewing
payments of the customer to whom the access token was issued.
If used with the tokens for anonymous sessions, the access is granted for the
payments of the anonymousId to which the access token was issued.
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.
manage_extensions:{projectKey}
Grants access to the APIs for creating, modifying and viewing anything related to API extensions in a project.
manage_project_settings:{projectKey}
Grants access to the API for modifying and viewing the project settings.
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.
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 1
{
"active": true,
"scope": "view_products:background-test-26",
"exp": 1501158800852
}Example Response 2
{
"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.