> For the complete documentation index, see [llms.txt](https://docs.zumrails.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zumrails.com/getting-started/your-zum-rails-account.md).

# Your Zum Rails Account

## Sandbox

Zūm Rails offers a sandbox environment for our clients to test integration and familiarize with the different areas of the product. Clients will be able to access the portal, use our APIs and SDK for testing purposes while using the sandbox environment.

You can reach out to our sales team to book a demo and get access to your Zūm Rails Sandbox environment.

[**Contact Sales**](https://zumrails.com/contact/)

In the sandbox environment, you can get access to your API credentials, test creation and management of users, payment instruments, transactions, and webhooks.

### **Get Access to API Credentials**

To call the Zūm Rails API you need an **API key**: a username and password pair used on the [Authenticate](https://docs.zumrails.com/api-reference/authentication.md#authenticate) endpoint. You manage your API keys in the portal under **Settings > Webhook & API Settings > API Keys**.

{% hint style="warning" %}
**Your current API credentials are now a Legacy API key and will expire on February 3, 2027.**

Since November 5, 2026, the API username and password you used before (the username is your customer ID) appear in the API Keys list with a **Legacy** badge and an expiry date. Create a new API key, update your integration to use it, and then disable the legacy key before that date. Both keys work at the same time, so you can switch without downtime.
{% endhint %}

#### Create an API key

1. In the portal, go to **Settings > Webhook & API Settings**. In the **API Keys** section, click **Create API key**.
2. Pick an **Expiry date**. It is required and can be any date from tomorrow up to 365 days from today. The key works until **23:59:59 UTC** on its expiry day.
3. Optionally, enter **Allowed IPs** (see [Restrict an API key to specific IPs](https://docs.zumrails.com/getting-started/your-zum-rails-account.md#restrict-an-api-key-to-specific-ips)).
4. Click **Create** and confirm.
5. Copy the **Username** and **Password** and store them securely, for example in your secrets manager.

{% hint style="danger" %}
The password is shown **only once**. It cannot be retrieved later. If you lose it, create a new API key and disable the old one.
{% endhint %}

Zūm Rails generates the username and password for you. Usernames start with `zr_test_` in sandbox and `zr_live_` in production, so you can tell environments apart.

You can have up to **5 active API keys** at the same time, legacy key included. For example, you can use one key per system or per environment. To create another key when you already have 5, disable one first.

#### API key list

The API Keys list shows every key your company has had, including disabled and expired ones:

| Column       | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| Username     | The key's username. The legacy key has a **Legacy** badge.       |
| Status       | **Active**, or **Inactive** once the key is disabled or expired. |
| Created date | When the key was created.                                        |
| Created by   | The portal user who created the key.                             |
| Expiry date  | The last day the key works (until 23:59:59 UTC).                 |
| Allowed IPs  | The IPs the key can be used from, or **All** if not restricted.  |

#### Rotate your API key without downtime

An API key's expiry date cannot be changed. To rotate:

1. Create a new API key.
2. Update your integration to authenticate with the new username and password.
3. Confirm your integration works with the new key.
4. Disable the old key.

#### Disable an API key

Click **Disable** on an active key and confirm. Disabling is **permanent**: the key stops working immediately, including any tokens already issued with it, and cannot be re-enabled. Disabled keys stay in the list as **Inactive**. Disable a key as soon as it is no longer used or if you think it has leaked.

#### Expiry and reminder emails

When an API key reaches its expiry date, it stops working and shows as **Inactive**.

Zūm Rails sends a reminder email every day during the 7 days before a key expires, and a final email when it expires. Emails include the key's username and expiry date, never its password. They are sent to:

* the emails configured for the **API key expiry** notification under **Settings > Notifications**, or your company email if none is configured;
* the portal user who created the key, if still active;
* your partner (in copy), if your account is managed by a partner.

Reminders stop once you disable the key.

#### Restrict an API key to specific IPs

You can restrict any active key, including the legacy key, so it only works from your servers' IP addresses. Set **Allowed IPs** when you create a key, or click **Edit** on an active key.

* Enter public IPv4 or IPv6 addresses, or ranges in CIDR notation, separated by semicolons. For example: `203.0.113.10; 198.51.100.0/24`.
* Leave it empty to allow any IP.
* Up to 20 entries. Duplicates, `*`, private, loopback and reserved addresses (such as `10.x.x.x`, `192.168.x.x` or `127.0.0.1`), and ranges wider than `/16` (IPv4) or `/48` (IPv6) are not accepted.
* The IP checked is the **public IP your requests come from** (your egress IP). If your servers are behind a NAT gateway or proxy, enter that IP or range.
* The restriction applies when authenticating and on every API call made with the token.
* Saving changes ends the key's active sessions. Your integration must authenticate again, and only the listed IPs are accepted.

Disabled or expired keys cannot be edited.

#### Who can manage API keys

* Portal users with the **View webhook & API settings** permission can see the API Keys list.
* Portal users with the **Create / disable API keys** permission can also create keys, disable keys and edit Allowed IPs. To give developers this access without full admin rights, create a custom role with this permission.
* Partners can manage the API keys of their sub-customers from the customer's **Webhook & API Settings**.

### **Start Testing**

* [Create & Manage Users](https://docs.zumrails.com/getting-started/quickstart.md#create-a-user)
* [Transactions](https://docs.zumrails.com/api-reference/transactions.md)
* [Webhooks](https://docs.zumrails.com/api-reference/webhooks.md)

## Production

Once your team has setup their sandbox environment and concluded the testing and integration, you can mirror your integration in the production environment to move money between your users. Reach out to our sales team to get started with using Zūm Rails in production environment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zumrails.com/getting-started/your-zum-rails-account.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
