API keys

Create publishable, secret, and restricted API keys, scope them with the permissions selector, and roll them when needed.

API keys are how your code talks to XPay. The dashboard manages two kinds: a fixed pair of standard keys (publishable + secret) for full access, and any number of restricted keys with a custom permission scope. Test mode and live mode have separate keys, so a key from one mode never works in the other.

This page covers where the keys live, how each kind works, the create-and-scope flow for restricted keys, how to roll a key, and the click-to-reveal flow.

What you can do

Use the standard pair

Every account has one Publishable key (safe for the browser) and one Secret key (server-side only) per mode.

Lock down with restricted keys

Create a named key that's allowed to do exactly what you need, nothing more. Helpful for read-only analytics or one-purpose integrations.

Roll keys when needed

Rotate a leaked key with one click. The old value stops working immediately and the new value is copied to your clipboard.

Switch test and live cleanly

Test mode and live mode have independent keys. The dashboard surfaces the right set based on the mode toggle.

Open the API keys page

Click Developers in the dashboard sidebar. The Developers page has three tabs: Overview, API keys, and Webhooks. Pick API keys.

The tab is split into two sections: Standard keys at the top (always two rows), and Restricted keys below (any number, with a Create restricted key button on the right).

If the tab is disabled in your dashboard, your role lacks the API-keys read permission. See Team and roles for which roles can access this surface.

Standard keys

Every merchant has a fixed pair of standard keys per mode:

Key	What it's for	Where to use it
Publishable key	Safe to embed in browser-side code. Identifies your account but can't read or modify private data.	The XPay JavaScript SDK, web checkout components, mobile clients.
Secret key	Full server-side access to the API. Treat it like a password.	Your backend, server-to-server jobs, scripts.

Both standard keys exist by default. They can't be deleted; they can only be rolled (rotated).

The dashboard description on the section reads: "A key that unlocks full API access, enabling extensive interaction with your account." That applies to the secret key. The publishable key carries the same identifier prefix but with no write or read access to private resources, so it's safe to ship to the client.

Restricted keys

Restricted keys are the recommended pattern when you want to limit blast radius. Each restricted key has:

A name that you set (3 to 255 characters).
A permission scope chosen per resource type, with three levels: None, Read, or Write. Setting Write implies Read automatically.

You can create as many restricted keys as you like. They're listed under the standard keys with a permission count badge; hovering it shows which resources got Read access vs Read-and-Write access.

Common patterns:

A read-only key for an internal analytics dashboard.
A write-scoped key for a single integration partner that only manages payment links.
A short-lived key for a contractor's local script.

Create a restricted key

Click Create restricted key

In the Restricted keys section, click Create restricted key in the top right. A side sheet opens, titled Create restricted API key.

Name the key

Enter a Key name between 3 and 255 characters. Pick something that names the integration or use case ("Analytics", "Webflow site", "Contractor cleanup"). The name is shown in the dashboard but never appears in the API or to customers.

Pick permissions

The permissions selector is a two-column table. The left column lists the resource types you can scope this key against; the right column has a None / Read / Write toggle for each row.

A row at the top labeled All resources is a master toggle: clicking None, Read, or Write stamps that level on every row at once. Use it to set a baseline, then tune individual rows.

Write implies Read for the same resource type. Selecting Write sends both read and write capabilities to the API, so you don't need to set both manually.

At least one permission must be set (Read or Write on at least one row), otherwise the key can't be created.

Click Create key

In the bottom of the sheet, click Create key. The new key is created and the full secret value is copied to your clipboard immediately. A "Restricted key created successfully" toast confirms.

Save the value somewhere safe. XPay will only show the prefix on the dashboard from this point on; the full value is never displayed again. To get a working key value back, click on the key's row to reveal it (see below).

Read a key

The token column shows each key's prefix followed by ••••••••. Click any row to reveal the full value:

Publishable keys are revealed and copied immediately when you click. They're safe to expose.
Secret and restricted keys require a 2-factor confirmation in live mode before the value is revealed and copied. In test mode, the click reveals immediately.

Once revealed, the value stays visible on that row until you navigate away. A "Copied to clipboard" toast confirms the copy each time you click.

Roll a key

Rolling a key revokes the old value and creates a new one in its place. Use roll when:

You think a key has been leaked or exposed in client code.
A teammate left and they had access to the secret.
You want to rotate keys on a regular schedule.

Open the action menu on any key (the ⋯ icon at the right of the row) and pick the roll option. A confirmation dialog explains the rotation. After confirming:

The old value stops working immediately. Any code still using it gets an authentication error.
A new value is generated and copied to your clipboard automatically.
The key keeps its name (for restricted keys) and permission scope.

Roll works on every key type, including standard keys. Plan the rotation: update your code with the new value before rolling, or be prepared for downtime while you swap.

Edit and delete a restricted key

Standard keys can't be edited or deleted. Restricted keys carry two extra options on the action menu:

Edit opens an Edit restricted API key sheet to update the name and permission scope. Saving applies immediately; existing requests using the key continue with the new scope.
Delete opens a confirmation dialog. Deleting revokes the key permanently. There's no undo, and any code still using it gets an authentication error on the next request.

Both actions are gated on the API-keys write permission. If your role lacks it, the menu items are disabled.

Test vs live mode

The keys you see depend on the mode toggle:

In test mode, the dashboard shows your test-mode standard keys and any test-mode restricted keys you've created. Calls to the test-mode API only work with these keys.
In live mode, the dashboard shows your live-mode standard keys and any live-mode restricted keys. Live-mode API calls only work with these keys.

A test-mode key never works against the live API and vice versa. Restricted keys live in one mode at a time; create a separate restricted key for each mode you need.

The 2-factor reveal step is enforced in live mode only. Test mode reveals immediately so you can grab keys without friction during development.