Aggregator

How Safepay aggregators are provisioned, identified, and authenticated.

Aggregators are top-level accounts that Safepay provisions for partners who process Raast payments on behalf of multiple businesses. Every integration starts with an aggregator: it scopes your merchants, generates credentials, and defines the compliance perimeter for your transactions.

Attribute	Description	Example
{{aggregator_id}}	Primary identifier for all API paths.	agg_2288490a-2176-4de5-b373-0ffb6f8e2e6e
{{secret_key}}	Aggregator secret sent in the X-SFPY-AGGREGATOR-SECRET-KEY header.	sk_live_c66a5b38-0ce1-4f83-8d72-57b8f91a8762
Environments	Sandbox and Production share the same aggregator ID but use separate keys.	Request additional secrets per environment.

Requesting access

1. Submit your request

   Email [e-mail] with your business details, use cases, and projected volume.

2. Safepay review

   Safepay provisions your aggregator and performs due diligence.

3. Receive credentials

   You receive:

   • {{aggregator_id}} (include in every API path)
   • At least one {{secret_key}} scoped to an environment
   • Dashboard access, if requested

Do not embed your secret key in mobile or web apps. Keep it in a server-side secret manager and rotate it immediately if compromised.

Authentication

All Raast API endpoints use the apiKey security scheme defined in the OpenAPI spec. Send X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}} with every request. Safepay rejects requests that rely on the deprecated Authorization: Bearer header.

Credential hygiene

• Maintain separate secrets per environment and workload (for example, one for payouts, another for pay-ins).
• Rotate keys proactively or whenever staff changes. Safepay can issue new keys through the Create access key endpoint.
• Use the Rotate access key endpoint to refresh keys without downtime.
• Monitor access with List access keys and disable unused keys with Delete access key.

Key endpoints

Endpoint	Purpose
GET /v1/aggregators/{{aggregator_id}}	Confirm aggregator metadata and validate credentials.
GET /v1/aggregators/{{aggregator_id}}/keys	List active access keys.
POST /v1/aggregators/{{aggregator_id}}/keys	Create new access keys for rotation.
PUT /v1/aggregators/{{aggregator_id}}/keys/{{access_key_id}}/rotate	Rotate a key without changing the token.

See also

• Create aggregator account
• Manage aggregator secret keys
• First API call
• API reference