KulPayAPI Live

API reference

Authentication

GET /v1/admin/keys

The account's API keys

Keys with their type (sk, rk, pk), scopes, last four characters and whether they are legacy (opaque keys issued before the kp_ format: rotate them). Requires admin:read or keys:manage.

Responses

  • 200 {data: [...]}

Request

curl -X GET "$KULPAY_URL/v1/admin/keys" \
  -H "Authorization: Bearer $KULPAY_KEY"
200 Response application/json 
{
  "data": [
    {
      "created_at": "2026-05-14T12:00:00Z",
      "id": "3K9gdgFU8tYDvMvO1agskQxf9LQ",
      "last4": "x9Qa",
      "last_used_at": "2026-10-11T08:59:31Z",
      "legacy": false,
      "mode": "test",
      "name": "Servidor da loja",
      "scopes": [
        "payments:read",
        "payments:write",
        "refunds:write"
      ],
      "status": "active",
      "type": "rk",
      "use_count": 18342
    },
    {
      "created_at": "2026-03-01T09:30:00Z",
      "id": "3KZvLCjA3YxljbE5HyYXiMogmjE",
      "last4": "T4mk",
      "legacy": false,
      "mode": "test",
      "name": "Relatórios",
      "revoked_at": "2026-09-30T17:12:05Z",
      "scopes": [
        "payments:read"
      ],
      "status": "revoked",
      "type": "rk",
      "use_count": 412
    }
  ]
}

POST /v1/admin/keys

Issue an API key

Keys look like kp_<live|test>_<sk|rk|pk>_<random><checksum> (PSP-8.1) and are shown once. type: sk gets every non-platform scope, rk the listed scopes, pk only checkout:write and tokens:write (PSP-8.2); without a type, listed scopes make an rk, none an sk. Requires admin:write or keys:manage.

Request body application/json required

FieldTypeDescription
namestring
scopesstring[]
typestring
One of: sk, rk, pk

Responses

  • 201 The key, with its secret this once.
  • 400 Unknown scopes or type. invalid_request

Request

curl -X POST "$KULPAY_URL/v1/admin/keys" \
  -H "Authorization: Bearer $KULPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "recon",
  "scopes": [
    "recon:read"
  ],
  "type": "rk"
}'
201 Response application/json 
{
  "created_at": "2026-10-10T22:15:44.211820237Z",
  "id": "3KWPqthUCgdYZBgaLTGUae2xfas",
  "last4": "71r8",
  "legacy": false,
  "mode": "test",
  "name": "recon",
  "scopes": [
    "recon:read"
  ],
  "secret": "kp_test_…",
  "status": "active",
  "type": "rk",
  "use_count": 0
}
400 Error · invalid_request application/problem+json 
{
  "code": "invalid_request",
  "detail": "The request body could not be parsed as valid JSON.",
  "error": {
    "code": "invalid_request",
    "message": "The request body could not be parsed as valid JSON."
  },
  "status": 400,
  "title": "Invalid request body",
  "type": "about:blank"
}

DELETE /v1/admin/keys/{id}

Revoke an API key

Parameters

NameInTypeDescription
id requiredpathstring

Responses

  • 204 Revoked.
  • 404 No such key for this account. not_found

Request

curl -X DELETE "$KULPAY_URL/v1/admin/keys/{id}" \
  -H "Authorization: Bearer $KULPAY_KEY"
404 Error · not_found application/problem+json 
{
  "code": "not_found",
  "detail": "The requested resource was not found.",
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found."
  },
  "status": 404,
  "title": "Not found",
  "type": "about:blank"
}

GET /v1/scopes

The scope catalogue

Every scope, what it allows, and the scopes of each key type (PSP-8.2). A restricted key (rk) lists its scopes; a secret key (sk) gets every non-platform scope; a publishable key (pk) only checkout:write and tokens:write. Aliases pass the gates they stand for: refunds:write passes payments:refund, recon:read and recon:resolve the reconciliation scopes. A call without its scope is 403 insufficient_scope with missing_scope. Any key may read this.

Responses

  • 200 {data: [{name, description, platform, grants}], key_types}.

Request

curl -X GET "$KULPAY_URL/v1/scopes" \
  -H "Authorization: Bearer $KULPAY_KEY"
200 Response application/json 
{
  "data": [
    {
      "description": "Read payments and their receipts.",
      "name": "payments:read"
    },
    {
      "description": "Create payments and cancel them.",
      "name": "payments:write"
    }
  ],
  "key_types": {
    "pk": {
      "description": "Publishable: tokenisation and checkout only.",
      "scopes": [
        "checkout:write",
        "tokens:write"
      ]
    },
    "rk": {
      "description": "Restricted: the scopes listed when it is issued."
    },
    "sk": {
      "description": "Secret: the account's full set (every non-platform scope).",
      "scopes": [
        "payments:read",
        "payments:write"
      ]
    }
  }
}