API credentials

The API credential object and the allowed CRUD operations on the related resource endpoint

API credentials are essential to obtain an access token from Commerce Core Layer API authorization endpoints so that you can make authenticated API calls or create the available Dashboard apps in case you're building your own Dashboard or extending the current one.

Each API credential is organization-specific and to create a new one you just need to provide a name and specify the API credential kind.

Please note that only Admins (i.e. users with an admin role) can perform all the CRUD actions on the API credentials of an organization, while Members (i.e. users with a read_only or custom role) are allowed only to retrieve a specific API credential and/or to fetch a list of API credentials.

Core API credentials

To use Commerce Core Layer API you need to be authorized in the first place. This means you need to get a valid access token. The permissions you're granted on each single resource authenticating with that token are determined by the type of API client you used to get it. Three different types of Core API credentials are currently available: sales_channel, integration, and webapp. Which one to use depends on your specific use case.

To create integration API credentials you also need to assign them a role with specific permissions. You cannot assign a role to sales_channel and webapp API credentials.

Sales channel

API credentials of kind sales_channel are used to build any customer touchpoint (e.g. your storefront with a fully functional shopping cart and checkout flow). They are not confidential (public) and their roles and permissions are restricted so that they can be safely used client-side and their tokens exposed to the public without any risks.

Integration

API credentials of kind integration are used to develop backend integrations with any 3rd-party system. They are confidential and can have one of two roles: admin or read_only.

Enterprise users can also define custom roles for their integration applications, specifying custom permissions on CRUD actions at the single resource level.

Webapp

API credentials of kind webapp are used to develop custom web apps or services for your users, extending Commerce Layer backend with any functionality that is not provided out of the box. You can use them to execute the OAuth 2.0 authorization code grant flow to get an access token after a user authorizes an app. They don't come with their own roles and permissions, since they get the set of permissions of the authenticated user.

Access token expiry

For security reasons, access tokens expire after a default period of time. Your access token lifetime differs based on the kind of application you're using. You can specify a custom lifetime for the token by setting the expires_in attribute at creation time or when updating a specific API credential.

The token lifetime value must be expressed in seconds and fall within a min of 2 hours (7200 secs) and a max of 1 year (31536000 secs).

To avoid security issues, be careful not to set too long expiration dates for your access tokens.

Dashboard apps API credentials

Each available Dashboard app has its own API credential kind (e.g. orders, shipments, imports, etc.) and comes with its predefined set of permissions in terms of CRUD action on the Core API resources. For more details about that please refer to the related section of the documentation:

pageApplications

Creating a hosted Dashboard app

The hosted version of any Dashboard apps can be created from the Dashboard UI by simply clicking on the related icon in the Hub section (that will create two API credentials of the selected kind, one for the test mode and the other for the live mode):

To do that via API you need to send a POST request to the /api/api_credentials endpoint, passing the specific name and kind as arguments in the request body:

Request

The following request creates the hosted Shipments app in live mode for the organization identified by the ID "ABCRtyUpBa":

curl -g -X POST \
  'https://provisioning.commercelayer.io/api/api_credentials' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "api_credentials",
    "attributes": {
      "name": "Shipments",
      "kind": "shipments",
      "mode": "live"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "ABCRtyUpBa"
        }
      }
    }
  }
}'

Response

On success, the API responds with a 201 Created status code, returning the created resource object:

{
  "data": {
    "id": "rpodBiRAON",
    "type": "api_credentials",
    "links": { ... },
    "attributes": {
      "name": "Shipments",
      "kind": "shipments",
      "confidential": true,
      "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
      "client_id": "XxYyZz__cl13nTID",
      "client_secret": "CL1eNTs3cRetXyZyKkXx",
      "scopes": "market:all",
      "expires_in": "7200",
      "mode": "live",
      "custom": false,
      "created_at": "2024-01-01T12:00:00.000Z",
      "updated_at": "2024-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": null
    },
    "relationships": {
      "organization": { ... },
      "role": { ... }
    }
  }
}

Creating a custom Dashboard app

Any Dashboard apps can be customized at your leisure by forking them and seamlessly integrating your custom version in the Dashboard itself. That can be done from the Dashboard UI by clicking on the Customizing apps section and following the simple steps of the wizard:

To create a custom app via API, send a POST request to the /api/api_credentials endpoint, passing the kind of the app you want to fork and the name you want to give to your custom app as arguments in the request body.

Make also sure to set the custom attribute to true and the URL where you're deploying your custom app as the redirect_uri.

Request

The following request creates a custom version of the Orders app in test mode for the organization identified by the ID "ABCRtyUpBa":

curl -g -X POST \
  'https://provisioning.commercelayer.io/api/api_credentials' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "api_credentials",
    "attributes": {
      "name": "My Orders App",
      "kind": "orders",
      "custom": "true",
      "redirect_uri": "https://mybrand.com/orders"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "ABCRtyUpBa"
        }
      }
    }
  }
}'

Response

On success, the API responds with a 201 Created status code, returning the created resource object:

{
  "data": {
    "id": "AGPkZiarvN",
    "type": "api_credentials",
    "links": { ... },
    "attributes": {
      "name": "My Orders App",
      "kind": "orders",
      "confidential": true,
      "redirect_uri": "https://mybrand.com/orders",
      "client_id": "KkWwHh__cl13nTID",
      "client_secret": "CL1eNTs3cRetZxZyKv",
      "scopes": "market:all",
      "expires_in": "7200",
      "mode": "test",
      "custom": true,
      "created_at": "2024-01-01T12:00:00.000Z",
      "updated_at": "2024-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": null
    },
    "relationships": {
      "organization": { ... },
      "role": { ... }
    }
  }
}

The newly created app will be automatically added to the Dashboard Hub under the Custom apps section.

Resources API credentials

API credentials of kind resources are automatically generated as soon as a new organization is created. They are used to populate and manage the Resources section of the Dashboard.

Resources API credentials are read-only, meaning that they cannot be created, deleted, or forked by the user. They are anyway returned when you fetch the list of an organization's API credentials.