> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-embedded-wallet-service/user-management.md).

# User Management

The User Management APIs allow a merchant to provision end users, retrieve their account information, submit KYC data, and check their verification status.

All User Management requests must be made from the merchant’s secure backend. These APIs must not be called directly from a browser or mobile application.

### Available APIs

| Method | Endpoint                         | Purpose                          |
| ------ | -------------------------------- | -------------------------------- |
| `POST` | `/whitelabel/users/signup`       | Create or link an end user       |
| `GET`  | `/whitelabel/users/get`          | Retrieve an end user             |
| `PUT`  | `/whitelabel/users/submitKyc`    | Submit or update KYC information |
| `GET`  | `/whitelabel/users/getKycStatus` | Retrieve detailed KYC status     |

***

## Authentication

Every request must include the following headers:

| Header            | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| `x-tlp-apikey`    | API key issued to the merchant                                  |
| `x-tlp-signature` | HMAC-SHA256 signature generated using the merchant’s API secret |
| `Content-Type`    | `application/json` for requests containing a body               |

The signature must be calculated using:

```
HMAC_SHA256(apiSecret, JSON.stringify(params))
```

For `GET` requests, `params` is the complete query object.

For `POST` and `PUT` requests, `params` is the complete request body.

The query or body must be sent exactly as it was signed, including the same:

* Field names
* Field order
* Data types
* Values

All requests are also subject to the merchant’s configured IP whitelist.

***

## End-User Identifiers

Existing users can be identified using any one of the following fields:

| Field            | Description                               |
| ---------------- | ----------------------------------------- |
| `endUserEmail`   | The end user’s registered email address   |
| `endUserId`      | The Tylt end-user ID                      |
| `externalUserId` | The merchant’s own unique user identifier |

Only one identifier is required.

The recommended identifier for integrations is `externalUserId`, as it allows the merchant to continue using its own internal user reference.The merchant should not allow the end user to initiate wallet transactions until KYC has been approved and `walletOpsAllowed` is `true`.

## Recommended User-Onboarding Flow

A typical user-onboarding process should follow this sequence:

1. Call `POST /whitelabel/users/signup` to create the end user.
2. Securely provide the TOTP enrollment information to the end user.
3. Submit KYC during signup or call `PUT /whitelabel/users/submitKyc`.
4. Call `GET /whitelabel/users/getKycStatus` until verification is complete.
5. Confirm that `walletOpsAllowed` is `true`.
6. Enable wallet functionality in the merchant’s application.
7. Use `GET /whitelabel/users/get` when a general user and wallet-access summary is required.

The merchant should not allow the end user to initiate wallet transactions until KYC has been approved and `walletOpsAllowed` is `true`.