Getting started

Authentication

Every request carries an API key as a bearer token. Keys are issued by the studio against one trade account, with a fixed set of scopes and a fixed environment.

Keys

curl "https://lucentimaging.com.au/api/print/v1/catalogue" \
  -H "Authorization: Bearer lpk_live_…"

A key looks like lpk_live_ or lpk_test_ followed by 64 hexadecimal characters. The Bearer scheme is matched case-insensitively; the key itself is not.

We store only a hash. The key is shown once, when it is created, and cannot be retrieved afterwards - if it is lost, the studio revokes it and issues another.

Keep keys server-side

A key spends your account's credit, so it must never reach a browser, a mobile app or anything else a customer can read. Keep it in your server environment and call us from your backend.

Authorisation is re-derived from your account on every request, so suspending an account or withdrawing its API access takes effect immediately across every key it holds.

Scopes

Scopes are fixed when a key is minted. A key without the scope an endpoint needs gets 403 - ask the studio for a key that carries it.

Scope	Grants	Notes
`price:read`	GET /catalogue, POST /quotes, GET /quotes/:id	Everything needed to show a price. Safe for a key that only quotes.
`orders:read`	GET /orders, GET /orders/:id	Read your own orders. Covers only orders placed through this API.
`orders:write`	POST /orders, POST /orders/:id/cancel, POST /uploads	Spends credit. Uploads sit here rather than with the reads because an upload URL is a write against our storage.

Live and test

A key belongs to one environment and cannot act in the other. A quote priced by a test key cannot be ordered by a live key, or the reverse - that is refused with QUOTE_ENVIRONMENT_MISMATCH. Reads are scoped the same way, so a test key cannot see, list or cancel live orders.

Test orders run the identical code path and price identically. What they skip is everything downstream: they are never printed, never sent to the studio floor, never invoiced for real, and generate no email to your customer. Build the whole integration against them.

When authentication fails

Missing, malformed, unknown, revoked, expired, and belonging-to-a-disabled-account all return the same bare 401. The response deliberately will not tell you which: distinguishing them would let anyone holding a candidate key learn whether it had ever been real.

Repeated authentication failures are rate limited separately, by source address rather than by key. If a key that worked yesterday stops working, contact the studio rather than retrying.

See errors for the full vocabulary and rate limits for the buckets.

Quickstart

Conventions