# API keys, scripts and assistants

The **API keys** screen makes keys for your own scripts and for AI assistants. A key can read your programme, members and reports, and change points or your programme if you allow it. Every change can be previewed before it is made, and every change and every read of customer data is recorded.

## Making a key

Open **API keys** in Matrix Rewards and press **Create a key**. Give it a name under **What is it for?**, tick what it may do, and create it. The key is shown once: copy it somewhere safe. Only a hash of its secret is kept, so a lost key cannot be shown again.

One key reaches every store on your account. Never paste it into a chat or a file you share.

## What a key may do

Each permission is a box you tick. A key can do only what its boxes allow:

- read your programme, members, reports, usage and the activity log;
- change members' points and cancel unused reward codes;
- change your programme: the earn rate, the bonuses, what a point is worth, the referral terms, when points expire, the rewards, and offers such as a double-points week;
- send changes to members' points, and changes to your programme, to a web address of yours (webhooks).

## Test keys and assistant keys

Tick **Test key — reads your real data, can only preview changes** to try the API safely: a test key sees your real data and can preview a change, but never makes one.

Tick **This key is for an AI assistant** for a key an assistant will use. An assistant's key cannot make a change in one step: it must first preview the change, then send it again with the confirmation the preview gave. It also moves your programme's money one step at a time: it never changes your point value or when points expire, each rate, bonus, referral payment and reward can at most double from where it stood before the assistant began (until a day passes with no change from it, or you change a figure yourself), and a new offer or reward can be no more generous than that step. The steps add up across figures: a doubled rate and a halved reward cost make an order worth four times as much in rewards. A bigger change is made in the app, or with a key that is not an assistant's. To lift these limits for one assistant's key, use **Lift limits** on it: it can then also change your point value and expiry, switch on letting shoppers spend any amount, and move any figure further than one step. Every change still needs the preview and its confirmation, which the assistant sends itself, so lift limits only for an assistant you trust; **Put limits back** ends it. An assistant's key can never manage webhooks or lift limits, lifted or not.

## Limits that protect you

- At most 100,000 points added, and 100,000 taken away, through keys in any 24 hours, across all your keys.
- At most 100 programme changes through keys in any 24 hours.
- Changes you make yourself in Matrix Rewards are not counted.

## Rotating and revoking

Rotate a key to get a new secret; the old one keeps working for a short time you choose, so a script can be moved over. Revoke a key the moment it leaks: it stops working at once.

The developer documentation, with every call and every error, is at [matrixrewards.co.uk/docs](https://matrixrewards.co.uk/docs.md).

---

Page: https://matrixrewards.co.uk/help/api-keys