# Client API Overview

https://dev.wisecp.com/es/client-api-overview

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

```bash
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.

## Related Articles

- [The WISECP API](https://dev.wisecp.com/en/the-wisecp-api)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [Client API First Calls](https://dev.wisecp.com/en/client-api-first-calls)