Manage aggregator secret keys

Securely handle the credentials that authenticate your Raast API calls.

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

1. 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.

2. Rotate regularly

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

3. 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

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
  }'

Rotate an access key

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

cURL

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

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}}

See also

• Quickstart
• Aggregator
• Errors
• Rate limits
• Access Keys API