Authentication

Overview

Pilon includes advanced authentication for customers, merchants and API clients. Our authentication is with JWT tokens. You will need a JWT token for both our REST and GraphQL API endpoints. To get a token, you will POST to our https://api.pilon.io/v1/token endpoint.

Token Scopes

Pilon supports the following token scopes:

Scope Where to use? Description
'public' Client / CORS Allows (together with an 'enivronment_id' credential, public access to an environment's data. This mainly means the public facing product catalog.
'customer' Client / CORS Allows access to one individual environment for a customer. So for example this allows adding products to a cart, checking out, browsing past order history, etc. Only for that single customer.
'environment' Server Allows full access to a single environment. This should be used server side only by the merchant.

The following sets of credentials will work with each token scope:

Scope Credential Sets
'public' 'environment_id'
'customer' Anonymous Customer Session
'environment_id', 'customer_session_id'
'customer' Authenticated Customer
'environment_id', 'customer_email', 'password'
'customer_id', 'password'
'environment_id', 'customer_email', 'client_id', 'client_secret'
'customer_id', 'client_id', 'client_secret'
'environment' 'client_id', 'client_secret'
'environment_id', 'user_id', 'password'

Client-Side Authentication

You can do client-side auth right from your front-end. For example a Vue SPA, Gatsby site Nuxt JS site, etc.

SECURITY NOTE: You will want to make sure you never share your client_secret credential with the client-side / browser. It is ok to send other credentials (environment_id, customer_id, password, etc) to the browser.

Step 1 | Request a JWT token

Via curl

Request a public scope token which will allow you to browse product catalog and access public store / environment data.

curl -X POST "https://api.pilon.io/v1/token" \
    -H "content-type: application/json" \
    -H "accept: application/json" \
    -d @- <<'EOF'    
{
    "token_scope": "public",
    "environment_id": "2eb32342-53f3-11e8-9ef5-6a0003055630"
}
EOF
1
2
3
4
5
6
7
8
9

If your credentials are valid, a response should come back like this:

{  
   "token":"MY_NEW_TOKEN",
   "token_scope":"public",
   "environment_id":"MY_ENVIRONMNET_ID",
   "customer_id":null,
   "expires_in":3600
}
1
2
3
4
5
6
7

Step 2 | Make an API call

For example, request a list of all products in the catalog for this environment.

Paste the contents of the "token" key from the JSON response above where the string MY_NEW_TOKEN appears in the Authorization header below:

Via curl

curl -X GET "https://api.pilon.io/v1/products" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer MY_NEW_TOKEN"
1
2
3

Server-Side Authentication

You can do server-side auth with admin or environment scope. You'll want to do this for running server-side scripts, building administrative features, etc.

Step 1 | Request a JWT token

Via curl

curl -X POST "https://api.pilon.io/v1/token" \
    -H "content-type: application/json" \
    -H "accept: application/json" \
    -d @- <<'EOF'    
{
    "token_scope": "environment",
    "environment_id": "2eb32342-53f3-11e8-9ef5-6a0003055630",
    "client_id":"MY_CLIENT_ID",
    "client_secret":"MY_SECRET"
}
EOF
1
2
3
4
5
6
7
8
9
10
11

If your credentials are valid, a response should come back like this:

{  
   "token":"MY_NEW_TOKEN",
   "token_scope":"environment",
   "environment_id":"MY_ENVIRONMNET_ID",
   "customer_id":null,
   "expires_in":3600
}
1
2
3
4
5
6
7

Step 2 | Make an API call

For example, request a list of all products in the catalog for this environment.

Paste the contents of the "token" key from the JSON response above where the string MY_NEW_TOKEN appears in the Authorization header below:

Via curl

curl -X GET "https://api.pilon.io/v1/products" \
    -H "accept: application/json" \
    -H "Authorization: Bearer MY_NEW_TOKEN"
1
2
3
Last Updated: 12/6/2018, 8:18:54 PM