> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laces.run/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference (v1)

> Base URL, authentication, and how to use the Try it playground with your own token.

Every endpoint of the Laces Partner API v1, generated from its
OpenAPI 3.1 spec. Each page has a
**Try it** button that sends a real request.

## Base URL

```text theme={null}
https://connect.laces.run/v1
```

Every path is relative to it: `POST /orders` is
`POST https://connect.laces.run/v1/orders`. This is the only host that
accepts partner credentials; sent anywhere else they get
`401 partner_credential_not_accepted`. There is one environment, production
([Testing your integration](/concepts/testing)).

## Authentication

| Scheme | Header | Routes |
| - | - | - |
| Bearer token | `Authorization: Bearer LCSTOK-…-X` | All routes except the token endpoint and health check |
| Publishable key | `X-Laces-Publishable-Key: LCSPUBK-…-X` | List events, get an event, create a checkout session. **Browser only.** |
| HTTP Basic (client id + secret) | `Authorization: Basic …` | [Create an access token](/api-reference/v1/oauth/token) only |

See [Authentication](/authentication) for the full rules.

## Using the playground

The playground sends requests **through Mintlify's proxy**, not from your
browser. That makes bearer-token calls work and publishable-key calls fail.

<Steps>
  <Step title="Get a token with curl">
    From your terminal:

    ```bash theme={null}
    curl -s -X POST "https://connect.laces.run/v1/oauth/token" \
      -u "$LACES_CLIENT_ID:$LACES_CLIENT_SECRET" \
      -d "grant_type=client_credentials"
    ```

    Copy `access_token` from the response. It is valid for one hour.
  </Step>

  <Step title="Paste it into Try it">
    Open any endpoint, press **Try it**, and paste the token into the
    **Authorization** (Bearer) field. Paste only the token
    (`LCSTOK-…-X`), not the word `Bearer`.
  </Step>

  <Step title="Send requests">
    Fill in the parameters and send. Remember that `POST /orders` and
    `/pay` need an `Idempotency-Key` header, and that a pay request on a mobile
    money order **sends a real prompt** to the number you enter.
  </Step>
</Steps>

| In the playground | Works? | Why |
| - | - | - |
| Routes with a **bearer token** | Yes | The proxy forwards your `Authorization` header |
| [Create an access token](/api-reference/v1/oauth/token) with Basic auth | Usually, but prefer curl | The proxy's request carries no browser `Origin`, so the token endpoint accepts it. But you'd be typing your live secret into a web page and sending it through a third party. |
| Routes with a **publishable key** | **No** | A publishable key needs a browser `Origin` that is one of your allowed domains. Proxied requests don't have one, so they get `403 origin_not_allowed`. Call those routes with a bearer token here, or try them from your own site. |

<Warning>
  The playground talks to production. Reads are harmless, but
  `POST /orders` creates a real order that holds places, and a pay request
  sends a real payment prompt. Use your [test event](/concepts/testing) and
  its free or low-price ticket.
</Warning>

<Info>
  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**.
</Info>

## Responses

Every route except the token endpoint returns the Laces envelope:

```json theme={null}
{ "code": 200, "message": "…", "data": { } }
```

On failure, `error` (human-readable) and `error_code` (stable; branch on this)
replace `data`. Every response has an `X-Request-Id` header to quote to
support. See [Errors](/concepts/errors).

## Versions

This is **v1**, the current version. Use the version switcher at the top of
the sidebar to move between API versions when more exist. A new version will
get its own base path (for example `/v2`); v1 keeps working at `/v1`. Changes
are announced in the [changelog](/changelog).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.