API referenceAgent keys

Agent keys

3 operations. Every schema and example on this page is generated from the platform contract.

GET/api/v1/agent/keys

List a store's agent API keys.

Returns key summaries (name, prefix, scopes, expiry, last used, revoked), never the secret or its hash.

auth merchant:readop listAgentKeysrate limited errors

Parameters

store_idstring · uuidqueryrequired

Store whose keys to list.

Response, 200

keysarray of objectrequired

8 child fields

idstringrequired

namestringrequired

key_prefixstringrequired

scopesarray of stringrequired

expires_atstring, nullablerequired

last_used_atstring, nullablerequired

created_atstringrequired

revoked_atstring, nullablerequired

curl -G "https://www.membber.com/api/v1/agent/keys" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/agent/keys", {
  params: { query: { store_id: "6659c139-0000-4000-8000-d0c500000066" } },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.listAgentKeys(
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066")
).ok.body.json

print(response)

Response, 200

{
  "keys": [
    {
      "id": "00000d1b-0000-4000-8000-d0c500000000",
      "name": "Example name",
      "key_prefix": "<key_prefix>",
      "scopes": [
        "<scope>"
      ],
      "expires_at": "<expires_at>",
      "last_used_at": "<last_used_at>",
      "created_at": "<created_at>",
      "revoked_at": "<revoked_at>"
    }
  ]
}

POST/api/v1/agent/keys

Issue a scoped API key for the AI agent surface.

Merchant issues a scoped key for their store. The full key is returned exactly once; only a hash is stored. Scopes are limited to read / approve / redeem-side operations, a key can never refund or redeem money.

auth merchant:writeop createAgentKeyidempotent retry rate limited errors

Request body

store_idstring · uuidrequired

Store the key is issued for (also authorises the merchant).

namestringrequired

A label so the merchant can recognise the key.

scopesarray of enumrequired

What the key may do (read / approve visits / redeem-side ops).

merchant:readstaff:approvestaff:redeem

expires_atstring · date-time, nullableoptional

Optional expiry (ISO). Omit for no expiry.

Response, 200

idstringrequired

keystringrequired

The full key, shown to the merchant exactly ONCE, never retrievable again.

key_prefixstringrequired

namestringrequired

scopesarray of stringrequired

expires_atstring, nullablerequired

created_atstringrequired

curl -X POST "https://www.membber.com/api/v1/agent/keys" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066",
    "name": "Example name",
    "scopes": [
      "merchant:read"
    ]
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.POST("/api/v1/agent/keys", {
  body: {
    store_id: "6659c139-0000-4000-8000-d0c500000066",
    name: "Example name",
    scopes: [
      "merchant:read"
    ]
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.createAgentKey(
    body: .json(.init(
        storeId: "6659c139-0000-4000-8000-d0c500000066",
        name: "Example name",
        scopes: [.merchant:read]
    ))
).ok.body.json

print(response)

Response, 200

{
  "id": "00000d1b-0000-4000-8000-d0c500000000",
  "key": "<key>",
  "key_prefix": "<key_prefix>",
  "name": "Example name",
  "scopes": [
    "<scope>"
  ],
  "expires_at": "<expires_at>",
  "created_at": "<created_at>"
}

DELETE/api/v1/agent/keys/{keyId}

Revoke an agent API key.

Immediately revokes a key (idempotent). A revoked key stops working near-instantly (§6.11 MED-9).

auth merchant:writeop revokeAgentKeyidempotent retry rate limited errors

Parameters

keyIdstringpathrequired

store_idstring · uuidqueryrequired

Store the key belongs to.

Response, 200

idstringrequired

revokedbooleanrequired

curl -X DELETE "https://www.membber.com/api/v1/agent/keys/06138bda-0000-4000-8000-d0c500000006?store_id=6659c139-0000-4000-8000-d0c500000066" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.DELETE("/api/v1/agent/keys/{keyId}", {
  params: { path: { keyId: "06138bda-0000-4000-8000-d0c500000006" }, query: { store_id: "6659c139-0000-4000-8000-d0c500000066" } },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.revokeAgentKey(
    path: .init(keyId: "06138bda-0000-4000-8000-d0c500000006"),
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066")
).ok.body.json

print(response)

Response, 200

{
  "id": "00000d1b-0000-4000-8000-d0c500000000",
  "revoked": true
}