• Version: 1.2.0

Authentication

The authentication system allows the Moltin API system to verify that you are an authorized user. It requires that you provide your client ID and secret that we provided when you created a store on our server. In return, you will receive a token string that will give you access to the APIs for one hour. Because cURL does not maintain a persistant connection, you will need to provide this token as a custom header (-H) with every cURL statement. All API examples are written with this in mind.

The authorization endpoints use OAuth 2.0 to verify requests, so you may be familiar with how that system works. It allows clients and end users to access API functionality without accessing the your Moltin user name and secret pair. We use several authentication types, which we will discuss below.

This topic covers the following processes:

The primary endpoint for authentication is https://api.molt.in/oauth/access_token, which uses the following data fields:

Key Type Required Unique Details
grant_type string Yes No The type of access token request. Valid options are “client_credentials”, which returns a new bearer token; “refresh_token”, which re-authorizes a bearer token provided with the request; and “authorization_code”, which authorizes applications that may access multiple stores.
client_id string Yes Yes The user ID that you received when you created your store on the Moltin servers.
client_secret string Yes Yes The password/secret that you received when you created your store on the Moltin servers.
refresh_token string No Yes If you are using the “refresh_token” type, this is the previously expired bearer token that you want to re-authorize.

Types of tokens

Moltin supports the following grant types:

  • Implicit
  • Client credentials

We uses scopes to define what a grant type can and can’t do on the API. There are specific use cases for these grant types, when to use them, and which SDK’s support them.

We define the scopes of accessibility as “read” and “write”. Where write means being able to manipulate the actual data on the endpoints and read is merely requesting the data.

Implicit

Implicit implements the following scopes over your store for the API:

Read:

  • products
  • categories
  • currencies
  • cart
  • checkout
  • brands
  • collections
  • shipping
  • flows
  • settings
  • taxes
  • files
  • customer tokens

Write

  • cart
  • checkout
  • customer tokens

We advise using implicit for client side code, and mobile applications, this means your data is more secure for interactions where your public key is visible whilst still giving you the ability to interact with the API.

The following SDK’s use the implicit grant type:

Client Credentials

Client credentials offers read and write access to all endpoints on the API:

Read/Write:

  • products
  • categories
  • customers
  • carts
  • currencies
  • brands
  • collections
  • shipping
  • flows
  • orders
  • taxes
  • settings
  • statistics
  • checkout
  • promotions
  • files
  • addresses
  • gateways
  • emails
  • webhooks
  • transactions
  • accounts
  • languages
  • cache
  • customer-tokens

We advise using client credentials when accessing the API from a backend server where your public is and secret are kept safe from the client side.

The following SDK’s use the client credentials grant type:

Create a Bearer Token

Before you start creating and modifying products, you’ll need a bearer token. This token will prove that you can access the Moltin API, so you’ll need to pass it as a custom header in every cURL statement. To get a new bearer token, use format below.

curl -X POST https://api.molt.in/oauth/access_token \
	-d "client_id={client id}" \
	-d "client_secret={client secret}" \
	-d "grant_type=client_credentials"

A successful response will return an HTML status code of 200 OK and a JSON array that looks like this:

{
	"access_token":"XXXXX",
	"token_type":"Bearer",
	"identifier":"client_credentials",
	"expires":1435690091,
	"expires_in":3600
}

The access_token field contains your bearer token. You can use it for the number of seconds specified by the expires_in field, which in this case is one hour. If your system allows it, this call will attempt to set an authization cookie within the HTML header.

Refresh a Bearer Token

When your token expires, you can re-authenticate your existing token. This saves the the confusion of tracking multiple tokens. This request differs in that you use the refresh_token grant_type and pass the expired bearer token as a data field.

curl -X POST https://api.molt.in/oauth/access_token \
	-d "client_id={client id}" \
	-d "client_secret={client secret}" \
	-d "grant_type=refresh_token"
	-d "refresh_token=XXXX"

This will return bearer token information as shown above. The expired token that you provided in the refresh_token field can now be used for requests for another hour. Like creating a new token, this request returns an HTML status of 200 OK on successful calls.

Using Authorization Codes

You must include the bearer token that you have received in the header of all future requests. All of the examples we show include the bearer token as a header line, but for reference, this is the format to include the token:

-H "Authorization: Bearer xxxxxxxxxx"

What Happens When the Token Expires

When the token expires, your next API call will fail with the following result:

{
  "status":false,
  "error":"Access token is not valid"
}

You’ll need to either refresh your token or create a new one. Our OAuth tokens expire in 3600 seconds (an hour).