Skip to main content
Every request to the Orchestra API requires authentication via an API key. This page explains how to create, manage, and secure your API keys.

​
Create an API Key

1

Open API Key Settings

In the Orchestra portal, go to API Keys.
2

Create New Key

Click Create to generate a new key.
3

Configure the Key

You can ignore the user settings entirely. If no user is selected, the API key is automatically assigned to your current user.
4

Save and Copy

Click Save. Your new API key will be displayed in a popup dialog.
Copy the key immediately and save it securely. Once you close the popup, you cannot view the API key again. If you lose it, you’ll need to create a new one.

​
Using Your API Key

Include the API key in the X-Api-Key header of every request:

​
User Assignment

When you assign an API key to a specific user:
  • The key can only access Payment Gateway Accounts assigned to that user
  • Transactions are logged under that user’s activity
  • Useful for multi-tenant setups or restricting access
If you don’t assign a user, the key has access to all Payment Gateway Accounts in your organization.

​
Security Best Practices

Never expose keys in client code

API keys should only exist on your server. Never include them in frontend JavaScript, mobile apps, or public repositories.

Use environment variables

Store keys in environment variables, not in code. Use secrets managers in production.

Rotate keys periodically

Create new keys and deprecate old ones on a regular schedule, especially if you suspect exposure.

Use separate keys per environment

Create distinct keys for development, staging, and production. Revoke dev keys if compromised without affecting production.

​
Rotating Keys

To rotate an API key:
  1. Create a new key
  2. Update your application to use the new key
  3. Verify the new key works in production
  4. Delete the old key
There’s no downtime during rotation. Both keys work until you delete the old one.

​
Revoking Keys

To revoke a compromised or unused key:
  1. Go to API Keys in the portal
  2. Find the key by name
  3. Click Delete or Revoke
The key stops working immediately.

​
Next: Capture and Charge

You’re ready to accept payments.

Payments Library

Recommended starting pointCapture payments in your frontend: pre-built UI with Google Pay, Apple Pay, and card entry. Handles 3D Secure automatically and keeps you out of PCI scope.

REST API

Backend operations after captureCharge tokens the Library captured, plus authorize/capture, refunds, voids, and recurring billing. Direct HTTP calls from your backend.
See how the Library and API work together.