Authentication

Before you can start using the Orbital API, you'll need to generate an API key. Each organization can have up to 5 active API keys at a time. Here's how to create one:

  • Log in to the Orbital Portal and go to your dashboard.
  • In the left-hand menu, select Ecommerce → Configurations. You'll see the API keys tab to view, create and manage your keys.
  • Click Create API Key to choose the type of access you want.

You’ll be asked to pick between two options:

Option A: Pay-ins Only

Choose this if your integration only needs to receive funds (e.g., customer crypto payments). This is considered a lower-risk key type.

  • Doesn't require approval from other users
  • Doesn't require IP whitelisting
  • Great for test environments, frontends, or read-only use cases

Once selected, name your key and click Create.

🔐

Pay-ins-only keys are more flexible, but still sensitive. The key will only be shown once make sure to store it securely.


Option B: Pay-ins and Pay-outs

Select this option if your integration will send and receive funds, such as initiating user payouts. This type includes more security features.

You'll be required to:

  • Whitelist at least one server IP address
  • Get approval from another authorized user on your Orbital account (multi-party authorization)

After entering a name for your key:

  1. Add the IP address of your server (you can add more later)
  2. Submit the key for approval
  3. Once approved, copy and store the key securely
🔐

IP whitelisting ensures only requests from known servers are allowed.
You can only use subnet masks between /24 and /32 anything broader will be rejected.

Add or Manage IP Addresses

If you're using a Pay-ins and Pay-outs key, you'll see an IP Whitelist tab. From here, you can view or update allowed IP addresses.

You can also add more IPs later if you're using multiple environments (e.g., staging, production). Just click Add another IP address.


Use Your API Key in Requests

Every API request must include your API key in the x-api-key header. If this is missing or incorrect, the request will fail.

x-api-key: YOUR_API_KEY


🛠 Troubleshooting

Here's a quick guide to common issues and how to fix them:

IssueWhat it meansHow to fix it
401 UnauthorizedMissing or incorrect API keyDouble-check your x-api-key header
Can't see the API key anymoreKeys are shown only onceDelete the key and create a new one
IP blockedThe request came from an unlisted IPAdd your IP in the dashboard (applies only to payout-enabled keys)
Invalid subnetYour IP range is too broadOnly /24 to /32 subnet masks are accepted
Key not workingNot approved or using an outdated keyConfirm approval is complete and you’re using the most recent key
Key limit reachedYou’ve already created 5 API keysDelete an unused key to make room for a new one

Need Help?

If you need assistance at any point: