Authenticating

The Corso Commerce API is protected, and can be accessed by requesting a token via an OAuth2 Client Credentials flow. This allows your application to authenticate with the Corso Commerce endpoint after requesting a token from https://auth.corso.com/oauth/token, and receiving a JWT in response. As a starting point for any questions about OAuth2 and the Client Credentials Flow, you can visit https://oauth.net/2/grant-types/client-credentials/. Specific implementation details are out of the scope of this documentation, but most languages, libraries, and frameworks have full support for this method of authentication.

If you have a valid, current JWT it can be used to access any endpoints in the Commerce API. At this time ALL available scopes are given to ALL clients authorized for the Commerce API.

Requesting and using an auth token looks like the following:

Additional details follow below.

Requesting a Token

To request an API token, POST an application/json request to https://api.corso.com/oauth/token with the following parameters:

Parameter Name	Description	Location
url	Set this to "https://auth.corso.com/oauth/token"	url
content-type	Set this to "application/x-www-form-urlencoded"	header
grant_type	Set this to "client_credentials".	body
client_id	Your Client ID	body
client_secret	Your Client Secret	body
audience	Set this to "commerce"	body

Note that developing against the Corso staging environment requires that you use https://auth.stg.corso.com/oauth/token instead.

An example curl for this endpoint might look like the following:

curl --request POST \
  --url 'https://auth.corso.com/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"client_id":"your_client_id","client_secret":"your_client_secret","audience":"dev.auth.corso.com","grant_type":"client_credentials"}'

Your client ID is equivalent to a username, and the client secret is equivalent to a password. Keep these credentials safe as you would any other secret in your application.

Token Responses

The response to a successful token request will be an HTTP 200, with a body similar to the following:

{
  "access_token": "eyJhbyfQ...adQssw5c",
  "token_type": "Bearer",
  "expires_in": 3600
}

Based on this response, the access_token value can be used as a Bearer token, and is valid for 1 hour (3600 seconds), although the expires_in value you might see may be different. The received JWT can be validated using the development language and framework of your choice.

Token Usage

To use this new token, pass the token in an authorization header, prefixed by Bearer . An example curl for retrieving an order from the Corso API might look something like the following:

curl --request GET \
  --url https://api.corso.com/v1/orders/123456789 \
  --header 'authorization: Bearer eyJhbyfQ...adQssw5c' \
  --header 'content-type: application/json'

Refreshing Tokens

Tokens are valid for the number of seconds conveyed by the expires_in value when the token was requested. Your application should persist the token for reuse and avoid excessive calls to the oauth/token endpoint, since those requests are rate-limited. Requesting a new token when the existing one has several minutes left generally works well.

The Commerce API does NOT support refresh tokens since it uses the Client Credentials flow; tokens can simply be re-requested at https://auth.corso.com/oauth/token as needed.

Authorization

At the present, permissions to all endpoints and operations are granted for any API client with access to the Commerce API. Your bearer token may be examined to see the specific scopes granted in the scopes claim, and the store ID's that you have access to in the store_id claim.

Because all currently exposed resources are "children" of an order, read:orders will also grant read access to fulfillments and line items.

Authorization is NOT distinct across stores. Any scopes held by a particular client_id will be applied to all stores associated.