Getting your API keys

Create an API key in the Laces app, copy the one-time secret, choose permissions and domains, and regenerate or revoke it later.

API keys are self-serve, in the Laces app. You need to be an owner or admin of the organization; other members don’t see the Developers entry.

There is one environment. The keys you create in the app are production keys: they work against https://connect.laces.run/v1 and take real payments. To build and test safely, see Testing your integration.

What you get

One API key in the app is one API client, and it has three values:

Value	Example	Secret?	Use it
Client ID	LCSCLI-EXAMPLECLNT2345EXAMP	No	On your server, with the secret, to get tokens
Secret (client secret)	LCSSECK-EXAMPLE…SECRE-X	Yes. Shown once.	On your server only
Publishable key	LCSPUBK-ABCDEFGHJKLMNPQRSTUVWXYZ23456789-X	No	In your web pages

Every key, token and id on this site is a made-up example value. Your real keys are issued to you in the Laces app, under Settings → Developers.

Create a key

1. Open Developers

   In the Laces app, go to Settings and scroll to the bottom. Tap Developers (“API keys, webhooks and integrations”). Only owners and admins see this tile.

   

   Settings, Get help section, with the Developers tile

   The first time you open Settings, a short guide highlights the tile. You can replay it any time from Settings → Get help → How to use the app.

   

   The Developers step of the Settings guide

2. Start a new key

   In API keys, tap Create key. Until you have made one, the section shows an empty state.

   

   Developers before any key exists

3. Name it

   Name is only for you, to tell keys apart, for example “Partner website” or “Club site”. Use one key per site, so you can revoke one without breaking the others.

   

   The Create API key form: name, permissions and the Read orders warning

4. Choose permissions

   Permissions are the scopes. Three are on by default: Read events, Create orders and Start hosted checkout.

   Read orders (orders:read) is off by default. It lets the key read every order in your organization including names, emails and phone numbers. Leave it off unless your server genuinely needs it; webhooks and checkout session reads tell you payment outcomes without it.

5. Enter your domains

   Two lists, explained below:

   • Allowed domains: websites that may use the publishable key, for example https://shop.example.com.
   • Return URL domains: websites a checkout may send people back to afterwards.

   

   Domains are added one at a time and shown as chips

6. Create it and copy the secret

   Tap Create key. The Your new key sheet shows the Client ID, the Secret and the Publishable key, each with a copy button. Copy all copies all three as a block you can paste into a .env file:

   .env

   LACES_CLIENT_ID=LCSCLI-EXAMPLECLNT2345EXAMP
   LACES_CLIENT_SECRET=LCSSECK-EXAMPLE…SECRE-X
   LACES_PUBLISHABLE_KEY=LCSPUBK-ABCDEFGHJKLMNPQRSTUVWXYZ23456789-X
   

   Copy the secret now and put it in your server’s secret manager or environment. Laces stores only a hash of it, so it can never be shown again. If you lose it, regenerate your keys.

   

   The secret is shown once (secret value blurred here)

   After you confirm, the key appears in your list with its secret masked to the last four characters.

   

   Your keys list

   Tap a key to open its detail screen, where you can edit permissions and domains, regenerate the keys or revoke the key.

   

   Key detail with Regenerate keys and Revoke key

The client secret (LCSSECK-…-X) is server-only. It mints tokens that can create and pay orders. Keep it in your server’s environment or secret manager, never in a browser, a mobile app or source control. The token endpoint refuses any request that carries an Origin header, so it cannot be called from a web page even by mistake.

An organization can have up to 10 active API keys.

Allowed domains vs return URL domains

List	Used for	Example
Allowed domains	Browser calls made with the publishable key. The browser’s Origin must match one entry exactly. Also the page that hosts an embedded checkout.	https://shop.example.com
Return URL domains	Where hosted checkout may send the buyer afterwards (on_success_url, on_cancel_url).	https://shop.example.com

Rules for both:

• Exact origins only: scheme, host and an optional port. No wildcards, no paths, no query strings.
  • https://shop.example.com is valid.
  • https://*.example.com and https://example.com/events are not.
• https only, with one exception for local development (below).
• https://example.com and https://www.example.com are different origins. List both if you serve both.
• Up to 20 entries per list.

If a list is empty, publishable-key calls (or hosted checkout sessions) are refused until you add your domains.

A domain you add can take up to 5 minutes before browsers’ CORS preflight requests from it succeed. Removing a domain, or removing a permission, takes effect on the next request.

Local development domains

You can add http://localhost:<port> or http://127.0.0.1:<port> to either list, for example http://localhost:3000. The port is required, and no other http address is accepted. These are exact entries like any other: http://localhost:3000 does not allow http://localhost:5173.

Local domains work end to end with your live keys: your local page can call the API with the publishable key, hosted checkout returns the buyer to an http://localhost:<port> return URL listed in Return URL domains, and the embedded checkout modal opens and completes inside a page on a listed http://localhost:<port> origin.

The app marks a key that lists one with “Local development domain: remove before launch”. Remove them once your site is live.

Webhook endpoint URLs are different: they are always public https addresses. See Webhooks.

Manage a key

Open the key from Developers → API keys to see its values, when it was last used, and its Key actions. You can edit the name, permissions and domains at any time. A permission you remove stops working on the next request, even for tokens already issued. A permission you add applies to tokens issued after the change, so fetch a new token to use it.

Regenerate keys

Regenerate keys replaces both the secret and the publishable key in one step. Use it if a secret leaks, if you lose it, or as routine rotation.

1. Tap Regenerate keys and read the confirmation. Tap Regenerate.

   

   The Regenerate keys confirmation

2. The app shows the new secret and the new publishable key once, with copy buttons and Copy all. Copy them now.

3. Deploy the new secret to your servers. The old secret keeps working for 24 hours, so there is no downtime on the server side.

4. Update your website with the new publishable key right away. The old publishable key stops working immediately.

Access tokens your server already holds are not cut off: a token issued with the old secret keeps working until it expires, at most 1 hour later. To shut out a leaked secret completely, revoke the key instead.

The change takes effect immediately. At most two secrets are valid at once, so regenerating again within 24 hours ends the oldest secret immediately. Finish one change before starting the next.

Revoke

Revoke key permanently disables the key: its tokens stop working, its publishable key stops working, and it cannot be reactivated. Create a new key instead. Revocation takes effect immediately, including for access tokens already issued.

Key formats

Every credential is uppercase and case-sensitive. Matching is exact, so a lowercased or edited key is rejected, never corrected. The random part uses A–Z and 2–9, without 0, O, 1 and I, so keys are unambiguous when read aloud or typed by hand.

Credential	Format	Where it lives
Publishable key	LCSPUBK-<32>-X	Browser or server. Public by design.
Client secret	LCSSECK-<52>-X	Server only
Client id	LCSCLI-<20>	Server. Not secret, but pairs with the secret.
Access token	LCSTOK-<52>-X	Server. Valid 1 hour.
Checkout session id	LCSCS-<21>	Appears in URLs
Webhook endpoint id	LCSWHE-<20>	Identifier only
Webhook signing secret	LCSWHSEC-<52>-X	Server only

<32> means 32 characters from that alphabet. The trailing -X is a fixed literal, not a placeholder.

A quick sanity check before you store a key:

const PUBLISHABLE = /^LCSPUBK-[A-HJ-NP-Z2-9]{32}-X$/;
const SECRET      = /^LCSSECK-[A-HJ-NP-Z2-9]{52}-X$/;
const CLIENT_ID   = /^LCSCLI-[A-HJ-NP-Z2-9]{20}$/;

Partner credentials work only on https://connect.laces.run. Sent to any other Laces host they are refused with 401 partner_credential_not_accepted.