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
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
}
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"
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
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
}
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"
2
3