Authenticating with the API

Authenticate Rain API requests with an API key, including key roles, custom permissions, and IP restrictions.

Rain API uses API keys for authentication. Every request to the API must include a valid API key in the Api-Key header.

Create your first API key

You can create API keys in the developer dashboard. Once you’ve created a key, you can view its value or revoke it if needed.

These manually created keys, known as primary keys, never expire unless you revoke them.

API key roles

When creating an API key via the API or dashboard, you can select a role to control access:

Role	Description
admin	Full access to all API operations
readonly	Read-only access to all resources
custom	Granular permissions configured per resource
webhookSigning	Used exclusively for signing webhook payloads

If you don’t provide a role, it defaults to admin.

Custom permissions

The custom role requires a permissions array. Each permission uses the resource:action format.

Available resources:

• applications - User and company applications
• automations - Payment routes
• balances - Balance information
• cardsAndShipping - Card creation and shipping
• companies - Company management
• users - User management
• contractsAndSignatures - Smart contracts and signatures
• payments - Payment operations
• paymentAccounts - Payment accounts
• quotes - Transfer quotes
• transfers - Transfers
• keys - API key management
• raindrops - Raindrops rewards: balances, activity, minting, statement credits, and custom redemptions
• raindrops-travel - Raindrops travel redemptions
• reports - Report access
• statements - Monthly statement downloads
• subtenants - Subtenant management
• transactionsAndDisputes - Transactions and disputes
• webhooks - Webhook configuration

Available actions:

• read - View resources
• write - Create and update resources
• delete - Delete resources

For example, to create a key that can only read transactions and create cards:

{
  "name": "Limited access key",
  "role": "custom",
  "permissions": ["transactionsAndDisputes:read", "cardsAndShipping:write"],
  "expiresAt": "2027-01-01T00:00:00Z"
}

Raindrops permissions

The raindrops and raindrops-travel resources scope a custom key to the Raindrops rewards endpoints without granting broader access. For example, you can create a key for testing rewards flows against production data instead of using an admin key.

Permission	Endpoints
raindrops:read	GET /v1/issuing/raindrops/activity GET /v1/issuing/raindrops/balance
raindrops:write	POST /v1/issuing/raindrops/mint POST /v1/issuing/raindrops/statement-credit POST /v1/issuing/raindrops/custom-redemption POST /v1/simulate/raindrops/mint-pending (sandbox only)
raindrops-travel:read	GET /v1/issuing/raindrops/travel-redemptions/balance
raindrops-travel:write	POST /v1/issuing/raindrops/travel-redemptions POST /v1/issuing/raindrops/travel-redemptions/{redemptionId}/refund

The raindrops resource does not cover the travel redemption endpoints. Those need raindrops-travel.

Create API keys programmatically

For managing API keys at scale, you can create API keys programmatically. These secondary keys must have:

• A name for identification.
• An expiry date in the future.

If a key is compromised or needs rotation, you can also revoke API keys before their expiry date. To delete an API key that is currently your primary or secondary webhook signing key, first set a different signing key.

Only primary keys can manage other API keys

• You cannot create a secondary key using a secondary key.
• You cannot revoke API keys using a secondary key.

IP address restrictions

You can restrict API key usage to specific IP addresses by providing an ipAddresses array when creating a key. This is optional. If you don’t specify any IP addresses, the key works from any location. You can specify up to 100 IP addresses per key.

When you configure IP address restrictions:

• Requests from allowed IP addresses succeed normally
• Requests from non-allowed IP addresses receive a 401 Unauthorized error with the message “Address invalid for API key”

Supported formats:

• IPv4 addresses (for example, 192.168.1.1)
• IPv6 addresses (for example, 2001:db8::1)
• CIDR ranges (for example, 10.0.0.0/24 or 2001:db8::/32)

For example:

{
  "name": "Production server key",
  "role": "admin",
  "expiresAt": "2027-01-01T00:00:00Z",
  "ipAddresses": [
    "203.0.113.50",
    "10.0.0.0/24"
  ]
}

Making authenticated API requests

To authenticate API requests, include your API key in the Api-Key header:

curl -X GET "https://api.rain.xyz/v1/example" \
     -H "Api-Key: YOUR_API_KEY"

Authenticate all API requests with an API key. You can find your API keys in the Rain dashboard under Config > API Keys.

Client-side considerations

Never expose API keys in client-side code, such as JavaScript or mobile apps.

Always use HTTPS when making API calls to protect your keys in transit.

See also

• Rain API overview: rate limits, response headers, and the full list of endpoint groups.
• Create an API key: provision and rotate keys programmatically.
• Idempotency for APIs: safely retry requests without duplicating operations.