Authorization for Admin APIs

Learn how to create an API client in Account Manager and use the API client’s credentials to request an access token for the Admin APIs.

Admin APIs are secured with Account Manager, but Shopper APIs are secured with the Shopper Login and API Access Service (SLAS) instead. This guide only covers how to access the Admin APIs. To learn how to access the Shopper APIs, see Authorization for Shopper APIs.

Before you create your API client for accessing the Admin APIs, you must know which API families you want to access and look up their OAuth scopes in the Authorization Scopes Catalog.

When you’ve prepared a list of all the scopes you need, come back to this guide and read on.

To use the Admin APIs, you (or someone with administrator access) must first create an API client by following these steps:

  1. Log in to Account Manager.

  2. Click API Client from the left navigation.

  3. Click Add API Client.

  4. In the Display Name field, enter unique and descriptive name for the API client. Example: Admin Client for Pia Larson.

  5. In the Password field, enter a secure password.

  6. In the Confirm Password field, reenter the password.

  7. Save the password (also known as the client secret) in a password manager or other secure location.

  8. Go to the Organizations section and do the following:

    • Click Add.
    • Select one or more organizations.
    • Click Add.
  9. Go to the Roles section and do the following:

    • Click Add.
    • Look for the Salesforce Commerce API category and select the Salesforce Commerce API.
    • Click Add.
    • Click the filter button.
    • Select an organization.
    • Enter the names of each instance that you want to access with the API client.
    • Select each instance.
    • Click Add.
  10. Go to the OpenID Connect section and do the following:

    • In the Default Scopes field, enter the following scopes (on separate lines):

    • In the Allowed Scopes field, enter the list of scopes that you prepared earlier. Enter each scope on a separate line.

      Associated screenshot -medium

    • For the Token Endpoint Auth Method field, select client_secret_post.

    • For the Access Token Format field, select JWT.

  11. In the Redirect URIs field, add http://localhost:8080.

  12. Click Save.

  13. Find your new API client in the table of API clients that appears after saving.

  14. Copy the value in the API Client ID column of the table. Example: 1d763261-6522-4913-9d52-5d947d3b94c4.

An API client that is used for the Salesforce Commerce API can’t be used for with the Open Commerce API (OCAPI), and vice versa. Each API framework (Salesforce Commerce API and OCAPI) requires its own API client. Also, an API client that is meant for OCAPI must not have the role “Salesforce Commerce API” assigned to it.

To request an access token for the Admin APIs, make a request to Account Manager’s oauth2 resource.

In the examples provided, we’re using Unix shell commands to set environment variables to simplify the formation of the request. If you’re not using a Unix-based operating system, you can do the string replacement manually or use a tool like Postman to handle variable substitution.

Credentials String

In your request, you must provide a credentials string in the HTTP header that is composed of your client ID, followed by a colon (:), followed by your client secret (password).

Use the following commands to format the credentials string correctly and save it as an environment variable.

Before running the following commands, replace the example client ID (1d763261-6522-4913-9d52-5d947d3b94c4) and example client secret (GS8KmdDEUKfWnEnv) with the credentials for the API client that you created earlier.

The Scope Parameter

Your request must also include additional information using the scope query parameter.

Although you can add roles for multiple instances to an API client, you can only request an access token for one instance at a time. To identify the instance that you want to associate with the access token, set its realm ID and instance ID as environment variables.

Before running the following commands, replace the example realm ID (zzte) and example instance ID (053) with the values for your B2C Commerce Instance. (To learn how to look up these values, see the Configuration Values guide.)

There’s one more string you must include in the scope parameter: a space-separated list of requested scopes. The requested scopes are checked against the list allowed scopes that you configured earlier for the client ID.

For our example, we only need one scope (sfcc.catalogs). If you’re requesting multiple scopes, separate them with spaces.

HTTP Request

Now that you’ve collected all the strings for the oauth2 endpoint, you can request an access token using an HTTP request like this:

If you’re not using environment variables, make sure to do the manual string replacement before running the curl command. Here’s what the same command looks like with example strings instead of environment variables:

Success Response

A successful request returns your access token as part of a JSON object:

With an access token from Account Manager (and the correct scopes), you can access any of the Admin APIs, including: Assignments, Catalogs, Customers, Inventory Availability, Orders, Products, and 8 more.

Now that you have set up your API client in Account Manager and know how to get an access token for Admin APIs, it’s time to make some API requests!

Learn how to formulate your API requests with the last guide in the Get Started series: Base URL and Request Formation.

To learn how to access the Shopper APIs, see Authorization for Shopper APIs.