API keys · Social Matter Payments API

GET /v1/api-keys

Every key of this merchant and its status (never the key itself)

Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Responses

Status	Meaning
`200`	The keys, oldest first
`401`	Error — error shape and codes
`403`	Error — error shape and codes

Fields of each item of `data` (200)

Field	Notes
`id`string	pattern `^ak_[0-9a-f]{24}$`
`object`string = "api_key"	—
`label`string	—
`prefix`string	The first 15 characters of the key
`site_id`string \| null	—
`status`enum	expiring = rotated, working until expires_at. one of `active`, `expiring`, `expired`, `revoked`
`expires_at`string \| null (date-time)	—
`revoked_at`string \| null (date-time)	—
`last_used_at`string \| null (date-time)	To the quarter hour
`created_at`string (date-time)	—
`current`boolean	The key this request came with

Example

List keys

GET /v1/api-keys

curl https://sandbox.socialmatterspay.com/v1/api-keys \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": [
    {
      "id": "ak_cdd8ac3a73ae2e907e98a139",
      "object": "api_key",
      "label": "Primary",
      "prefix": "sk_sandbox_b8ed",
      "site_id": null,
      "status": "active",
      "expires_at": null,
      "revoked_at": null,
      "last_used_at": "2026-10-28T00:22:34.406Z",
      "created_at": "2026-10-28T00:22:34.395Z",
      "current": true
    },
    {
      "id": "ak_712aae48d8a5ea7d8c5336bd",
      "object": "api_key",
      "label": "Wholesale store",
      "prefix": "sk_sandbox_7ab3",
      "site_id": "site_3d810c4cb0b887ef83ca99c8",
      "status": "active",
      "expires_at": null,
      "revoked_at": null,
      "last_used_at": null,
      "created_at": "2026-10-28T00:22:39.867Z",
      "current": false
    }
  ]
}

POST /v1/api-keys

Another key, for the merchant or one of its sites; the key is in this response only

Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

Request body

Field	Notes
`label` requiredstring	1–100 characters
`site_id`string	The key acts for this site only

Responses

Status	Meaning
`201`	The new key, shown once
`400`	Error — error shape and codes
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes
`422`	Error — error shape and codes

Fields of `data` (201)

Field	Notes
`id`string	pattern `^ak_[0-9a-f]{24}$`
`object`string = "api_key"	—
`label`string	—
`prefix`string	The first 15 characters of the key
`site_id`string \| null	—
`status`enum	expiring = rotated, working until expires_at. one of `active`, `expiring`, `expired`, `revoked`
`expires_at`string \| null (date-time)	—
`revoked_at`string \| null (date-time)	—
`last_used_at`string \| null (date-time)	To the quarter hour
`created_at`string (date-time)	—
`current`boolean	The key this request came with
`key`string	sk_live_… or sk_sandbox_…; shown only here

Example

A key that acts for one site

POST /v1/api-keys

curl -X POST https://sandbox.socialmatterspay.com/v1/api-keys \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "label": "Wholesale store",
  "site_id": "site_3d810c4cb0b887ef83ca99c8"
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "ak_712aae48d8a5ea7d8c5336bd",
    "object": "api_key",
    "label": "Wholesale store",
    "prefix": "sk_sandbox_7ab3",
    "site_id": "site_3d810c4cb0b887ef83ca99c8",
    "status": "active",
    "expires_at": null,
    "revoked_at": null,
    "last_used_at": null,
    "created_at": "2026-10-28T00:22:39.867Z",
    "current": false,
    "key": "sk_sandbox_…"
  }
}

POST /v1/api-keys/{id}/rotate

Issue the replacement now; the old key keeps working until the overlap ends

Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

The replacement has the old key's label and site. The old key's expires_at becomes now + expires_in_hours (default 24, 1 to 168), or stays sooner if it was already set. Rotating the key the dashboard shows makes the replacement the one it shows. The body is optional.

Parameters

Field	Notes
`id` requiredpath · string	—

Request body

Field	Notes
`expires_in_hours`integer	1 to 168. default `24`

Responses

Status	Meaning
`201`	The replacement, shown once, and when the old key stops
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (201)

Field Notes

idstring pattern ^ak_[0-9a-f]{24}$

objectstring = "api_key" —

labelstring —

prefixstring The first 15 characters of the key

site_idstring | null —

statusenum expiring = rotated, working until expires_at. one of active, expiring, expired, revoked

expires_atstring | null (date-time) —

revoked_atstring | null (date-time) —

last_used_atstring | null (date-time) To the quarter hour

created_atstring (date-time) —

currentboolean The key this request came with

keystring sk_live_… or sk_sandbox_…; shown only here

replacesobject

3 child fields

`id`string	—
`prefix`string	—
`expires_at`string (date-time)	—

Example

Rotate a key; the old one works for the overlap

POST /v1/api-keys/ak_712aae48d8a5ea7d8c5336bd/rotate

curl -X POST https://sandbox.socialmatterspay.com/v1/api-keys/ak_712aae48d8a5ea7d8c5336bd/rotate \
  -H 'Authorization: Bearer sk_sandbox_…' \
  -H 'Content-Type: application/json' \
  -d '{
  "expires_in_hours": 24
}'

Response · 201

HTTP 201
Cache-Control: no-store

{
  "data": {
    "id": "ak_0434deede69824be39cff34f",
    "object": "api_key",
    "label": "Wholesale store",
    "prefix": "sk_sandbox_8a81",
    "site_id": "site_3d810c4cb0b887ef83ca99c8",
    "status": "active",
    "expires_at": null,
    "revoked_at": null,
    "last_used_at": null,
    "created_at": "2026-10-28T00:22:39.874Z",
    "current": false,
    "key": "sk_sandbox_…",
    "replaces": {
      "id": "ak_712aae48d8a5ea7d8c5336bd",
      "prefix": "sk_sandbox_7ab3",
      "expires_at": "2026-10-29T00:22:39.874Z"
    }
  }
}

DELETE /v1/api-keys/{id}

Revoke a key now

Secret key

Host https://api.socialmatterspay.com · https://sandbox.socialmatterspay.com

409 last_merchant_key for the last working merchant-wide key; rotate or create a replacement first.

Parameters

Field	Notes
`id` requiredpath · string	—

Responses

Status	Meaning
`200`	The revoked key
`403`	Error — error shape and codes
`404`	Error — error shape and codes
`409`	Error — error shape and codes

Fields of `data` (200)

The same fields as under listApiKeys.

Example

Revoke the old key now

DELETE /v1/api-keys/ak_712aae48d8a5ea7d8c5336bd

curl -X DELETE https://sandbox.socialmatterspay.com/v1/api-keys/ak_712aae48d8a5ea7d8c5336bd \
  -H 'Authorization: Bearer sk_sandbox_…'

Response · 200

HTTP 200
Cache-Control: no-store

{
  "data": {
    "id": "ak_712aae48d8a5ea7d8c5336bd",
    "object": "api_key",
    "label": "Wholesale store",
    "prefix": "sk_sandbox_7ab3",
    "site_id": "site_3d810c4cb0b887ef83ca99c8",
    "status": "revoked",
    "expires_at": "2026-10-29T00:22:39.874Z",
    "revoked_at": "2026-10-28T00:22:39.877Z",
    "last_used_at": null,
    "created_at": "2026-10-28T00:22:39.867Z",
    "current": false
  }
}

Every key of this merchant and its status (never the key itself)

Responses

Fields of each item of data (200)

Another key, for the merchant or one of its sites; the key is in this response only

Request body

Responses

Fields of data (201)

Issue the replacement now; the old key keeps working until the overlap ends

Parameters

Request body

Responses

Fields of data (201)

Revoke a key now

Parameters

Responses

Fields of data (200)

Fields of each item of `data` (200)

Fields of `data` (201)

Fields of `data` (201)

Fields of `data` (200)