> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/set-up-access). 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 manually revoked.

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

<Info>
  If a role is not provided, it defaults to `admin`.
</Info>

### 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 balance, activity, and 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:

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

## Create API keys programmatically

For managing API keys at scale, you can [create API keys programmatically](/reference/keys/create-a-key). 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](/reference/keys/delete-a-key) before their expiry date. To delete an API key that is currently your primary or secondary [webhook signing key](/docs/set-up-webhooks#webhook-security-and-signing), first set a different signing key.

<Warning>
  #### 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.
</Warning>

## 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 IP address restrictions are configured:

* 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:

```json theme={null}
{
  "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:

```bash theme={null}
curl -X GET "https://api.rain.xyz/v1/example" \
     -H "Api-Key: YOUR_API_KEY"
```

All API requests must be authenticated using an API key. You can find your API keys in the Rain dashboard under **Config > API Keys**.

<Image align="center" width="600px" alt="API Keys section of the Rain dashboard" src="https://files.readme.io/aa9d54bab0a2d9f69b6a56d5626ac101bfc0d356d3b2bdd29b8d1125eb86924d-api-keys.png" />

## 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 prevent keys from being intercepted.

## See also

* [Rain API overview](/reference/rain-api): rate limits, response headers, and the full list of endpoint groups.
* [Create an API key](/reference/keys/create-a-key): provision and rotate keys programmatically.
* [Idempotency for APIs](/reference/idempotency): safely retry requests without duplicating operations.