Manage aggregator secret keys

Safepay issues an aggregator secret key ({{secret_key}}) after approving your account. All API requests must include it in the X-SFPY-AGGREGATOR-SECRET-KEY header.

Key format

sk_live_c66a5b38-0ce1-4f83-8d72-57b8f91a8762

Best practices

Store in a secret manager

Use AWS Secrets Manager, HashiCorp Vault, or your platform’s equivalent. Restrict read permissions to the services that call Safepay.

Rotate regularly

Rotate keys every 90 days or sooner when staff changes. You can create overlapping keys to achieve zero-downtime rotation.

Separate by workload

Issue unique keys for payouts vs pay-ins so you can revoke one without disrupting the other.

Create or rotate keys via API

Use the Access Keys API to automate issuance. Set {{base_url}} to https://dev.api.getsafepay.com/raastwire in Sandbox or https://api.getsafepay.com/raastwire in Production.

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/keys" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "payouts-service",
    "is_active": true
  }'

const baseUrl = '{{base_url}}';
const aggregatorId = '{{aggregator_id}}';
const secretKey = process.env.SAFEPAY_SECRET_KEY ?? '';

type CreateAccessKeyPayload = {
  api_version: string;
  data: {
    token: string;
    secret: string;
    name: string;
    is_active: boolean;
  };
};

const res = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/keys`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-SFPY-AGGREGATOR-SECRET-KEY': secretKey,
    },
    body: JSON.stringify({
      name: 'payouts-service',
      is_active: true,
    }),
  },
);

if (!res.ok) {
  throw new Error(`Key creation failed: ${res.status}`);
}

const payload: CreateAccessKeyPayload = await res.json();
const accessKey = payload.data.token;
const secretKey = payload.data.secret;

Rotate an access key

Use rotation to issue a new secret without changing the access key token.

curl --request PUT "{{base_url}}/v1/aggregators/{{aggregator_id}}/keys/{{access_key_id}}/rotate" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

const baseUrl = '{{base_url}}';
const aggregatorId = '{{aggregator_id}}';
const accessKeyId = '{{access_key_id}}';
const secretKey = process.env.SAFEPAY_SECRET_KEY ?? '';

const res = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/keys/${accessKeyId}/rotate`,
  {
    method: 'PUT',
    headers: {
      'X-SFPY-AGGREGATOR-SECRET-KEY': secretKey,
    },
  },
);

if (!res.ok) {
  throw new Error(`Key rotation failed: ${res.status}`);
}

List, update, and revoke keys

Use List access keys to audit active credentials.
Use Update access key to deactivate or rename keys.
Use Delete access key to revoke compromised credentials.

Always revoke compromised keys immediately using Delete access key and issue replacements.

Header usage reminder

X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}

Getting started

Integration guides

Use Cases

Concepts

Reference

Key format

Best practices

Create or rotate keys via API

Rotate an access key

List, update, and revoke keys

Header usage reminder

See also

​Key format

​Best practices

​Create or rotate keys via API

​Rotate an access key

​List, update, and revoke keys

​Header usage reminder

​See also

Key format

Best practices

Create or rotate keys via API

Rotate an access key

List, update, and revoke keys

Header usage reminder

See also