Migrating from Token API v0 to API clients

As of September 2023, authentication with our APIs must be done via API clients. NewStore will stop supporting authenticating with integration users soon. This article describes how to migrate the authentication for your API calls.

The new token endpoint is using the Client Credentials Grant and requires a client_id/client_secret pair.

The migration requires two steps:

1. Creating an API client as a one-time action
2. Obtaining a temporary access token with API client credentials

Creating API client

note

This feature is only available to users with Admin privileges by default. To allow other roles to manage API clients, grant them the Manage API clients permission.

1. Navigate to the NewStore Omnichannel Manager.
2. Go to Settings - User & Roles - API clients.
3. Create an API Client by providing a name, optional description, token TTL and select scopes or Support Legacy APIs.
   note

   Support Legacy APIs means no scopes are associated with the client. Scope validation is only enforced by APIs documented on the developer portal.

4. Copy the client_id and client_secret.
   Important

   Save the client_secret to a secure location as it is revealed only during the client creation.

5. Use the credentials to obtain an access token as described in the next section.

Obtaining access token

Use the following code snippet to first exchange the OAuth2 API client credentials for an access token. The access token is an object containing information for authorizing client requests and refreshing the token itself.

curl -X POST \
  --url 'https://id.p.newstore.net/auth/realms/{tenant}/protocol/openid-connect/token' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id={CLIENT_ID}' \
  --data-urlencode 'client_secret={CLIENT_SECRET}'

In the above snippet, adjust the following data:

• tenant is typically the name of your company, plus a stage variable. For example:
  • company-sandbox
  • company-staging
  • company (production)
• CLIENT_ID and CLIENT_SECRET from the API client created in the first step of this article.

The response from the token method looks similar to this:

{
    "access_token": "eyJhbGciOiJ....",
    "expires_in": 86400,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

Include the returned token in the Authorization header of a request:

Authorization: Bearer <access_token from the response above>

note

The new tokens are compatible with all exposed endpoints.