Skip to content

Latest commit

 

History

History
44 lines (24 loc) · 4.86 KB

03.md

File metadata and controls

44 lines (24 loc) · 4.86 KB
Raw

Getting Started with Commerce Layer

The best way to get started is to create an account and try the API (you can use our Postman collection to run quick tests).

Creating or Seeding Commerce Data

Once you sign up, you have two configuration options:

  1. The onboarding tutorial for faster environment configuration with some seed (test) data—adequately set up and ready to go.

  2. The manual configuration guide to manually create all the required resources in the correct order (based on their mutual relationships) and configure your organization step-by-step. (this could take a while longer, but it's a good opportunity to dig deeper into how Commerce Layer works and learn more about how its data model is structured—I highly recommend new users follow this path).

Both options use the Commerce Layer CLI so that you complete the whole process without leaving the command line.

API credentials

All requests to Commerce Layer API must be authenticated with an OAuth2 bearer token. To get an access token, you need to execute an authorization flow by using a valid application type as the client. Each application type has its usage, authentication flow, and permissions. There are three application types:

  1. Sales channel: for client-side public usage with a market a scope (i.e. only SKU, prices, stock items, stock locations associated with the market are returned. e.g ecommerce websites and mobile apps).

  2. Integration: for developing backend integrations with any third-party system (e.g, interacting with Commerce Layer CLI or Zapier).

  3. Webapp: for developing custom web applications or services, extending Commerce Layer backend with any functionality that is not provided out of the box. (e.g a mobile application or hardware device for logistic operators that just want to create in Commerce Layer parcels for a shipment by scanning the EAN code)

Each of these applications can be authenticated with different authorization grant flows using the available authorization grant types as described in the table below:

Commerce Layer authorization flows table

  • The client credentials grant type gives you a “guest” access token to both sales channel and integration applications.
  • The password grant type gives you an access token to sales channel applications in exchange for customer credentials.
  • The authorization code grant type is used by backend applications to exchange an authorization code for an access token.
  • The refresh token grant type is used by clients to exchange a refresh token for an expired access token.

Each access token generated based on the application types gets a specific set of permissions. For example, sales channel applications can read resource lists only for SKUs, SKU options, prices, promotions, and bundles. Anything outside this will require another application type. You can read the documentation to learn more about the available roles and permissions or for further information on authentication with Commerce Layer API. We also have a JavaScript authentication library you can easily use in your client to generate any type of access token.

Access Token Expiration

For security reasons, access tokens expire after a default time. An access token lifetime differs based on the kind of API credentials in use; you can check them here in the documentation. Regardless of the default durations, you can specify a custom lifetime for the token at the API credentials level on the admin dashboard when you create/update each of them (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 (especially the sales channel ones, usually used client-side) because they cannot be revoked (i.e. even if you request a new one, the old one will stay valid until its original expiration date).

<< previous lesson | next lesson >>