Authentication

Storefront API requires authorization only for certain actions associated with user account (e.g. updating saved addresses) or manipulating cart and checkout.

​

For guest users

​

Using X-Spree-Order-Token header

Cart and Checkout endpoints paths also allow interactions without the bearer token to allow creating and managing guest checkouts.

When you first create a cart via:

curl --request POST \
  --url 'https://demo.spreecommerce.org/api/v2/storefront/cart?fields%5Bcart%5D=number%2Ctoken' \
  --header 'Content-Type: application/vnd.api+json'

You’ll receive a response containing an empty cart. This response also contains a data.token attribute.

{
  "data": {
    "id": "114",
    "type": "cart",
    "attributes": {
      "number": "R522550303",
      "token": "NswjLVjZOw4OpEm1yWqlJg1713367317414"
    },
    "relationships": {}
  }
}

You can store this token in the frontend session (eg. Session Storage or a cookie) and pass it in a X-Spree-Order-Token: {token} header.

​

For signed in users

For users who have an account in your store, you will need to generate oAuth tokens to authenticate requests to endpoints such as Account, Cart and Checkout.

​

Generating OAuth token

To obtain a token, execute the following curl command:

curl -X POST http://localhost:3000/spree_oauth/token \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data "grant_type=password&username=spree@example.com&password=spree123"

You should receive a JSON response with a access_token and a refresh_token, eg.

{
  "access_token": "CmVXoDp6f5Y51s2xFAAdSbdT5wcGZIuGKKr27zAkBvQ",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "g5xPzY51_QYyok-ZcH9f4_btBkT_RZ6pB7ugGRaMjQQ",
  "created_at": 1713367848
}

​

Refreshing OAuth token

OAuth tokens obtained via the previous step are valid only for a specific time (defined in expires_in attribute).

After that period, you can refresh the token by executing the following curl command:

curl -X POST http://localhost:3000/spree_oauth/token \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --data "grant_type=refresh_token&refresh_token=g5xPzY51_QYyok-ZcH9f4_btBkT_RZ6pB7ugGRaMjQQ"

On a success, you’ll receive a new bearer token to use when accessing the API, eg.

{
  "access_token": "JVMcaoCkxV4o2xofhAwf7ReeFEWUM94ZnVSKRITd3TQ",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "nMlyfxfA9U6xfSDnFhoZQzL4IOkDc-EkW1y66ZTf5Oc",
  "created_at": 1713367950
}