Client API Overview

3 views Markdown

The surface a customer uses on their own account, and the ways it deliberately differs from the admin one.

Overview

The client API lets a customer drive their own account from their own code: read services, pay an invoice, order a domain, open a ticket. The key belongs to the customer, not to you, and the customer issues it from their account.

Everything it reaches is bounded to that one account. The scope is not a filter you remember to apply; it comes from the key and cannot be widened by anything in the request.

It is a separate product from the admin surface, not a restricted view of it. Different address, different kind of key, and a shorter catalogue built from what a customer can actually do in their panel.

Prerequisites

A customer account on the installation, and a client key issued from /api-credentials in that account.
The base address /api/v1/client. An admin key sent here is refused, and so is a client key sent to the admin surface.

Structure

Four things behave differently here, and knowing them up front saves reading two catalogues side by side.

Every query is account-bound A record belonging to someone else answers 404, exactly like a record that does not exist. The two are never distinguished, so a key cannot probe for its neighbours.

Universal values travel as codes Countries are ISO two-letter codes and currencies are ISO codes, in both directions. Internal numeric ids are not part of this surface.

Money is an object, dates are plain Amounts arrive as {amount, currency} rather than a formatted string, and dates as YYYY-MM-DD or null. Formatting is yours to do.

Anything a form would pick has a lookup Where the panel offers a dropdown, the API offers a reference endpoint: countries, then that country's states, then that state's cities.

What Stays in the Panel

Some account work has no endpoint at all, and that is a boundary rather than a gap. Card storage needs the payment provider's own hosted flow. Changing a password or an email address needs a one-time code. Two-factor setup and identity documents need a person. Data-deletion requests are a legal decision.

Their state is still readable, so an integration can tell whether an account is verified without being able to verify it.

Example

who the key belongs to

curl -H 'Authorization: Bearer wck_...' \
     'https://panel.example.com/api/v1/client/whoami'
# {"data":{"id":3,"type":"client","owner_id":42,"permissions":["Services/*"]}}

curl -H 'Authorization: Bearer wck_...' \
     'https://panel.example.com/api/v1/client/services?limit=10'

Pitfalls

Do not build an operator tool on client keys

Serving many customers from one integration means one key per customer, each issued by that customer. If you need to act across accounts, that is the admin surface. Collecting customers' keys to fake it is a liability you do not want to hold.

Payment is balance or a stored card, nothing else

Ordering and paying accept the account balance or a card the customer already saved. Gateway flows that need a redirect, an iframe or a 3-D Secure step belong to the panel. A declined card still answers 200 with a failed payment on it, so read the payment status, not only the HTTP code.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Overview

Prerequisites

Structure

What Stays in the Panel

Example

Pitfalls

Related Articles