> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate requests to the Storefront API.

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](/api-reference/storefront/cart) and [Checkout](/api-reference/storefront/checkout) endpoints paths also allow interactions without the bearer token to allow creating and managing guest checkouts.

When you first create a cart via:

```bash theme={"theme":"night-owl"}
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.

```json theme={"theme":"night-owl"}
{
  "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](/api-reference/storefront/account), [Cart](/api-reference/storefront/cart) and [Checkout](/api-reference/storefront/checkout).

### Generating OAuth token

To obtain a token, execute the following curl command:

```bash theme={"theme":"night-owl"}
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.

```json theme={"theme":"night-owl"}
{
  "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:

```bash theme={"theme":"night-owl"}
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.

```json theme={"theme":"night-owl"}
{
  "access_token": "JVMcaoCkxV4o2xofhAwf7ReeFEWUM94ZnVSKRITd3TQ",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "nMlyfxfA9U6xfSDnFhoZQzL4IOkDc-EkW1y66ZTf5Oc",
  "created_at": 1713367950
}
```