> For the complete documentation index, see [llms.txt](https://api.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.shopwaive.com/classic/api-keys-and-shopify-expiring-tokens.md).

# API keys and Shopify expiring tokens

Why the Shopwaive API uses API keys now, and how to move an integration off an old store access token

## Why this changed

Shopify now gives apps access tokens that expire. A store's token changes every hour, so it cannot be your credential for the Shopwaive API.

Shopwaive moved every store to expiring tokens in October 2026. A Shopwaive API key takes the place of the old single store token, the one that never expired. A key does not expire. It works until you revoke it or uninstall Shopwaive.

## What to do

{% stepper %}
{% step %}
**Open Settings**

In your Shopify admin, open the **Shopwaive** app and click **Settings** in the app menu.
{% endstep %}

{% step %}
**Open Developers**

Click **Developers**. The **Shopwaive API keys** card shows how many keys are active.
{% endstep %}

{% step %}
**Create a key**

Under **Shopwaive API keys**, type a label (for example `ERP sync`). If your integration changes balances (a deposit, a set, a void or an order) or starts workflows (`POST /api/trigger`), tick **Change balances through the REST API (wallets:write)**: the old token could do that. A key with only **Start Shopify Flow from another store (flow:trigger)** can start workflows, but it cannot read or change balances. Leave the other boxes empty unless you use the [Loyalty API](https://api.shopwaive.com/classic/reference/rest-api-documentation/loyalty-api.md). Then click **Create API key**.
{% endstep %}

{% step %}
**Copy the key**

Click **Copy**. The full key is shown only once.
{% endstep %}

{% step %}
**Send the key**

In your integration, send the key in the `X-Shopwaive-Access-Token` header in place of the old token.

With a key, every request that changes something (`POST` and `PUT /api/customer`, `POST` and `DELETE /api/action/{actionid}`, and `POST /api/trigger`) also needs an `Idempotency-Key` header: a new value for each change, for example a UUID, and the same value when you retry it. Without it, the request returns HTTP `400` and changes nothing.
{% endstep %}
{% endstepper %}

The header name does not change. Only its value changes:

```bash
curl --location 'https://app.shopwaive.com/api/customer/customer@example.com' \
--header 'X-Shopwaive-Access-Token: swak_EXAMPLEKEY000000000000000000000000000000' \
--header 'X-Shopwaive-Platform: shopify' \
--header 'Content-Type: application/json'
```

`swak_EXAMPLEKEY000000000000000000000000000000` is an example. Use your own key. The [Quick Start](https://api.shopwaive.com/classic/quick-start.md) has the same request in Node and PHP.

## What happens to old tokens

A Shopwaive API key starts with `swak_`. Any other value in the `X-Shopwaive-Access-Token` header is an old token. Move every integration to a key now.

No key, or a token Shopwaive does not know, returns HTTP `401`: see [If a key is not accepted](https://api.shopwaive.com/classic/quick-start.md#if-a-key-is-not-accepted).

## FAQ

* **Do I need one key for each integration?** One key is enough. You can make one for each developer or integration, so you can revoke one without stopping the others.
* **Can I see a key again later?** No. It is shown only once. If you lose it, revoke it and create a new one.
* **Can I put a key in my theme?** No. Anyone can read theme code and any code that runs in a browser. Keep keys on your server.
* **Do I change anything else in my requests?** Keep the same URLs and the `X-Shopwaive-Platform` header. A read needs nothing else. A request that changes something also needs an `Idempotency-Key` header: see **Send the key** above.
* **What if a request returns an error?** The message names the reason. See [If a key is not accepted](https://api.shopwaive.com/classic/quick-start.md#if-a-key-is-not-accepted).
