Refresh API Key

Refresh API key with grace period

post

Refreshes a merchant's API key, generating a new key while keeping the old key valid during a grace period. This allows merchants to rotate their API keys seamlessly without service interruption. Both keys will work during the grace period.

Body

application/json

Request to refresh an existing API key with a grace period

api_keystringRequired

The actual API key to refresh

grace_period_minutesinteger · min: 1 · max: 60 · nullableOptional

Grace period in minutes during which both old and new API keys are valid (1-60 minutes)

namestring · nullableOptional

Optional new name for the API key

Responses

200

API key refreshed successfully

application/json

400

Key already deprecated, expired, or invalid

application/json

404

API key not found

application/json

429

Rate limit exceeded

application/json

500

Unexpected error occurred

application/json

post

/v1/merchant/api_key/refresh

HTTPcURLJavaScriptPython

POST /v1/merchant/api_key/refresh HTTP/1.1
Host: gateway.stage.pay.io
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "api_key": "hm_abc123xyz789def456...",
  "grace_period_minutes": 30,
  "name": "Production API Key v2"
}

{
  "data": {
    "grace_period": {
      "ends_at": "2026-01-09T12:30:00Z",
      "minutes": 30
    },
    "message": "API key refreshed successfully. Both keys will work for the next 30 minutes. Please update your integration with the new key.",
    "new_api_key": "sk_live_abc123xyz789...",
    "new_api_key_hint": "sk_live_abc...789",
    "new_api_key_id": "api_key_xyz789",
    "old_api_key_id": "api_key_abc123"
  },
  "success": true
}