Getting Started

Authentication

Every request to the Modulate Partner API must include your API key

The Modulate Partner API uses API key authentication. Include your key in every request using the X-Partner-API-Key header.

Example request
$curl https://getmodulate.dev/api/partner/merchants \
>  -H "X-Partner-API-Key: YOUR_API_KEY"

Getting your API key

API keys are provisioned by the Aurora Payments team. To request one:

  1. Log in to your Partner Portal account
  2. Contact your account manager or email help@getmodulate.dev
  3. You’ll receive your key via secure channel — store it somewhere safe

Keep your API key private. Do not embed it in client-side code or commit it to source control. Treat it like a password.

Using your key

Pass your API key as a request header on every call:

$X-Partner-API-Key: YOUR_API_KEY
$curl https://getmodulate.dev/api/partner/merchants \
>  -H "X-Partner-API-Key: YOUR_API_KEY"

Verifying your key

GET /api/partner/me returns the identity behind the key you just sent — your organization, the key’s own prefix and environment, its scopes, and the per-minute limits that apply to it. It is the quickest way to confirm a new key works, and the only place to look up your organization_id.

Check which key you are using
$curl https://getmodulate.dev/api/partner/me \
>  -H "X-Partner-API-Key: YOUR_API_KEY"
Response
1{
2  "data": {
3    "organization_id": "3f9a1c2e-5b7d-4e10-9c33-8ad2e6f10b44",
4    "organization_name": "Example Payments",
5    "key_id": "8c1d4f60-2e93-4a55-b7c1-0d9e3a5f2b18",
6    "key_prefix": "pk_live_a1b2",
7    "label": "Production - Main",
8    "environment": "production",
9    "scopes": ["partner:read"],
10    "rate_limits": {
11      "standard_per_minute": 120,
12      "ai_per_minute": 5,
13      "window_seconds": 60
14    }
15  },
16  "meta": { "request_id": "req_abc123", "api_version": "v1" },
17  "errors": []
18}

No endpoint asks you to supply your organization_id — every request is scoped automatically by the key you send. /me reports it for your own logging and support requests.

Error responses

If authentication fails, you’ll receive one of these responses:

StatusCodeMeaning
401AUTHENTICATION_REQUIREDX-Partner-API-Key header is missing
401AUTHENTICATION_REQUIREDAPI key is invalid or has been revoked
403INSUFFICIENT_SCOPEKey exists but lacks permission for this endpoint
Example error response
1{
2  "error": {
3    "code": "AUTHENTICATION_REQUIRED",
4    "message": "Missing X-Partner-API-Key header",
5    "request_id": "req_abc123"
6  }
7}

Key scopes

API keys are scoped to control access. Currently available scope:

ScopeAccess
partner:readFull read access to merchants, pricing, transactions, statements, and residuals

Additional write scopes (e.g. merchant updates) are on the roadmap. Contact your account manager to discuss early access.

Rotating your key

If your key is compromised, contact help@getmodulate.dev immediately to revoke the old key and issue a new one.