# Account

What this key is and what it reaches.

Part of [the API reference, version 2026-10](https://matrixrewards.co.uk/docs/api/2026-10.md). Every address below starts with the base address:

```text
https://app.matrixrewards.co.uk/api/2026-10
```

## The account this key belongs to, its stores, and the key's own scopes {#getMe}

`GET /me` — the full address is `https://app.matrixrewards.co.uk/api/2026-10/me`.

**Needs:** any valid key; no permission needed.

Needs no scope beyond a valid key: a client's first call should not have to guess what it may do.

### The answer

The account, its stores and this key.

| Field | Type | Always there | What it is |
| --- | --- | --- | --- |
| `api_version` | string | yes | — |
| `account` | object, or null | yes | — |
| `account.id` | string | yes | — |
| `account.name` | string | yes | — |
| `account.wallet_scope` | one of `site`, `account` | yes | 'account' means one balance shared across the account's stores. |
| `account.created_at` | string | yes | — |
| `stores` | list of object (`Store`) | yes | — |
| `stores[].key` | string | yes | — |
| `stores[].name` | string | yes | — |
| `stores[].platform` | string | yes | 'shopify' today; the engine ingests events, so another platform is another producer. |
| `stores[].external_ref` | string, or null | yes | That platform's own identifier — a myshopify domain, for instance. |
| `stores[].created_at` | string | yes | — |
| `stores[].display_name` | string | yes | The store's name as every page shows it: the design's `storeName`, else the name Shopify has for the shop now, else the name it was installed with. `name` stays the name it was installed with. |
| `key` | object | yes | — |
| `key.id` | string | yes | — |
| `key.name` | string | yes | — |
| `key.mode` | one of `live`, `test` | yes | — |
| `key.scopes` | list of [`Scope` values](https://matrixrewards.co.uk/docs/authentication.md#permissions) | yes | — |
| `key.agent` | boolean | yes | Tagged by the merchant as being for an AI assistant. |
| `key.limits_lifted` | boolean | yes | True when the merchant has lifted this assistant key's fixed limits on the API keys screen of the Matrix Rewards app: its programme changes are then not held to the assistant limits (what a point is worth, expiry, one step a day). It still needs a preview's confirmation for every change, and still cannot manage webhooks. Only a person can lift or restore the limits, in the app; no API call can. Always false for a key that is not for an assistant. |
| `key.used_previous_secret` | boolean | yes | True when this call used the previous secret during a rotation grace window. |
| `rate_limit` | object | yes | — |
| `rate_limit.limit` | integer | yes | — |
| `rate_limit.remaining` | integer | yes | — |
| `rate_limit.reset` | integer | yes | Unix seconds at which the bucket is full again. |

**Headers on the answer:** `Request-Id`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. [What each header means](https://matrixrewards.co.uk/docs/api/2026-10.md#headers).

### Example

```bash
curl "https://app.matrixrewards.co.uk/api/2026-10/me" \
  -H "Authorization: Bearer $MATRIX_API_KEY"
```

The answer:

```json
{
  "api_version": "2026-10",
  "account": {
    "id": "acc_example",
    "name": "Example Retail Ltd",
    "wallet_scope": "site",
    "created_at": "2026-08-03T09:12:00Z"
  },
  "stores": [
    {
      "key": "example-outlet",
      "name": "Example Outlet",
      "platform": "shopify",
      "external_ref": "example-outlet.myshopify.com",
      "created_at": "2026-08-20T14:30:00Z",
      "display_name": "Example Outlet"
    },
    {
      "key": "example-store",
      "name": "Example Store",
      "platform": "shopify",
      "external_ref": "example-store.myshopify.com",
      "created_at": "2026-08-03T09:12:00Z",
      "display_name": "Example Store"
    }
  ],
  "key": {
    "id": "Kx7Qp2Lm9Vt4Rz8N",
    "name": "Nightly export",
    "mode": "live",
    "scopes": [
      "manage_keys",
      "read_audit",
      "read_members",
      "read_programme",
      "read_reports",
      "read_usage",
      "write_members",
      "write_webhooks"
    ],
    "agent": false,
    "limits_lifted": false,
    "used_previous_secret": false
  },
  "rate_limit": {
    "limit": 120,
    "remaining": 119,
    "reset": 1789552801
  }
}
```

### Other answers

| Status | What it means | Error pages |
| --- | --- | --- |
| 401 | `unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer. | [unauthenticated](https://matrixrewards.co.uk/docs/errors/unauthenticated.md) |
| 429 | `rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait. | [rate_limited](https://matrixrewards.co.uk/docs/errors/rate_limited.md) |

## The API keys on this account {#listKeys}

`GET /keys` — the full address is `https://app.matrixrewards.co.uk/api/2026-10/keys`.

**Needs:** the `manage_keys` permission (in the app: “The list of your keys (not their secrets)”).

Never the secret half: the row keeps a keyed hash of it. A key whose plaintext was lost is rotated, not recovered. Keys are created, rotated and revoked in the app's API keys screen, behind a Shopify staff session — no scope mints a key, because a key that could mint keys could widen its own reach.

### The answer

The keys.

| Field | Type | Always there | What it is |
| --- | --- | --- | --- |
| `data` | list of object | yes | — |
| `data[].id` | string | yes | — |
| `data[].name` | string | yes | — |
| `data[].mode` | one of `live`, `test` | yes | — |
| `data[].scopes` | list of [`Scope` values](https://matrixrewards.co.uk/docs/authentication.md#permissions) | yes | — |
| `data[].agent` | boolean | yes | — |
| `data[].limits_lifted` | boolean | yes | True when the merchant has lifted this assistant key's fixed limits in the app (see `Me.key.limits_lifted`). |
| `data[].created_at` | string | yes | — |
| `data[].last_used_at` | string, or null | yes | — |
| `data[].revoked_at` | string, or null | yes | — |
| `data[].rotation_grace_until` | string, or null | yes | — |
| `has_more` | boolean | yes | — |
| `next_cursor` | string, or null | yes | — |

**Headers on the answer:** `Request-Id`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. [What each header means](https://matrixrewards.co.uk/docs/api/2026-10.md#headers).

### Example

```bash
curl "https://app.matrixrewards.co.uk/api/2026-10/keys" \
  -H "Authorization: Bearer $MATRIX_API_KEY"
```

The answer:

```json
{
  "data": [
    {
      "id": "Kx7Qp2Lm9Vt4Rz8N",
      "name": "Nightly export",
      "mode": "live",
      "scopes": [
        "manage_keys",
        "read_audit",
        "read_members",
        "read_programme",
        "read_reports",
        "read_usage",
        "write_members",
        "write_webhooks"
      ],
      "agent": false,
      "limits_lifted": false,
      "created_at": "2026-09-01T08:00:00Z",
      "last_used_at": "2026-09-16T10:00:00Z",
      "revoked_at": null,
      "rotation_grace_until": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### Other answers

| Status | What it means | Error pages |
| --- | --- | --- |
| 401 | `unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer. | [unauthenticated](https://matrixrewards.co.uk/docs/errors/unauthenticated.md) |
| 403 | `forbidden_scope`: the key does not carry the scope this call needs; `required_scope` says which. | [forbidden_scope](https://matrixrewards.co.uk/docs/errors/forbidden_scope.md) |
| 429 | `rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait. | [rate_limited](https://matrixrewards.co.uk/docs/errors/rate_limited.md) |

## Stop the key making this request, immediately {#revokeThisKey}

`POST /keys/self/revoke` — the full address is `https://app.matrixrewards.co.uk/api/2026-10/keys/self/revoke`.

**Needs:** any valid key; no permission needed.

Needs no scope: presenting the key is the authorisation. It takes no identifier, so it cannot revoke any key but the one signing the request — which is what makes it safe to leave unscoped. Use it the moment a key is believed to have leaked; a merchant can also revoke any key from the app's API keys screen. The revoke and its audit entry are one transaction, and so is deleting every webhook endpoint the key created (`webhook.delete` for each, with the reason and the key's id).

### The answer

The key is revoked. It will not authenticate again.

| Field | Type | Always there | What it is |
| --- | --- | --- | --- |
| `ok` | boolean | yes | — |
| `key_id` | string | yes | — |
| `revoked_at` | string | yes | — |

**Headers on the answer:** `Request-Id`. [What each header means](https://matrixrewards.co.uk/docs/api/2026-10.md#headers).

### Example

```bash
curl -X POST "https://app.matrixrewards.co.uk/api/2026-10/keys/self/revoke" \
  -H "Authorization: Bearer $MATRIX_API_KEY"
```

The answer:

```json
{
  "ok": true,
  "key_id": "3D1wN9KfD8595Al5",
  "revoked_at": "2026-09-16T10:00:00Z"
}
```

### Other answers

| Status | What it means | Error pages |
| --- | --- | --- |
| 401 | `unauthenticated`: no usable API key was presented. Malformed, unknown, revoked and wrong-secret are one answer. | [unauthenticated](https://matrixrewards.co.uk/docs/errors/unauthenticated.md) |
| 404 | `not_found`: this key was revoked a moment ago, by another request. | [not_found](https://matrixrewards.co.uk/docs/errors/not_found.md) |
| 429 | `rate_limited`: too many requests for this key; `bucket` says which allowance. `Retry-After` says how long to wait. | [rate_limited](https://matrixrewards.co.uk/docs/errors/rate_limited.md) |

---

Page: https://matrixrewards.co.uk/docs/api/2026-10/account
Contract: 2026-10 sha256:35af153960028890fea5738799f5a71e535e1eea4dd3f6b8d5f50b37f02363da