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

# Onboarding

> How to request Partner API access and register keys (manual only).

# Onboarding

Partner API access is **manual only**. There is no self-serve signup, no public registration form, and **no automatic onboarding** — and none is planned.

IMBA enables a tenant only after reviewing the applicant’s business. Keys and credentials are issued or registered only in that manual process.

## 1. Request access

Email **[support@imbawallet.com](mailto:support@imbawallet.com)** with a clear subject, for example:

```text theme={null}
Partner API onboarding — <Your Company Legal Name>
```

In the body, include at least:

| Item                                             | Why                                         |
| ------------------------------------------------ | ------------------------------------------- |
| Legal company name + country of incorporation    | KYC / compliance                            |
| Business website and short product description   | Use-case review                             |
| Contact person (name, role, email)               | Ongoing coordination                        |
| Approximate volumes (cards / eSIM / gift / USDT) | Capacity & product setup                    |
| Preferred products                               | Cards, eSIM, gift, withdraw — as applicable |
| Webhook HTTPS URL (if already known)             | Can also be agreed later                    |

Do **not** attach private keys. Do not send secrets in the first email.

We will reply from support after an initial review. Until then, API credentials are not created.

## 2. After we contact you — create and share keys

Only after IMBA has contacted you and confirmed next steps should you generate keys and send **public** material.

You will typically need **two separate keypairs**:

| Key             | Algorithm   | Purpose                        | What you send to IMBA         |
| --------------- | ----------- | ------------------------------ | ----------------------------- |
| API signing     | **Ed25519** | Sign assertion JWTs (`kid`)    | **Public** key + chosen `kid` |
| Card encryption | **X25519**  | Receive `card_encrypted` (JWE) | **Public** key                |

Never email or chat your **private** keys. Private keys stay on your servers only.

### 2.1 Ed25519 signing key (API)

Generate a keypair on a secure machine (examples):

```bash theme={null}
# OpenSSL 3.x
openssl genpkey -algorithm ED25519 -out partner_ed25519_private.pem
openssl pkey -in partner_ed25519_private.pem -pubout -out partner_ed25519_public.pem
```

Choose a stable key id, e.g. `key_1` or `prod-2026-07`.

Send to IMBA (via the channel they specify — usually reply to support):

* `kid`
* Ed25519 **public** key (PEM or agreed encoding)
* Environment you want enabled (production)

Keep `partner_ed25519_private.pem` offline from email and tickets.

### 2.2 X25519 key (card JWE)

Required when cards use the default JWE payload mode.

```bash theme={null}
# Example with OpenSSL (OKP / X25519)
openssl genpkey -algorithm X25519 -out partner_x25519_private.pem
openssl pkey -in partner_x25519_private.pem -pubout -out partner_x25519_public.pem
```

Send only the **public** key. See [Card encryption](/guides/card-encryption).

### 2.3 Webhook secret

You propose:

* HTTPS webhook URL
* HMAC secret (high-entropy random string you generate)

IMBA registers them on your tenant. You verify deliveries with `X-IMBA-Signature` — see [Webhooks](/guides/webhooks).

Do not reuse the Ed25519 or X25519 private keys as the HMAC secret.

## 3. What IMBA configures manually

After business approval and key exchange, IMBA sets up (by hand):

1. `partner_id` and contract state
2. Registered Ed25519 credential (`kid` + public key) and scopes
3. Webhook URL + HMAC secret
4. X25519 JWE public key (for card tenants)
5. Product allowlists / catalogs as agreed (cards, eSIM, gift)

You then follow [Quickstart](/guides/quickstart) and [Authentication](/guides/authentication).

## 4. Rules

* **No automatic onboarding** — email + business review + manual setup only
* **No automatic key issuance** — you generate keys; IMBA registers public material after approval
* Private keys never leave your custody
* Rotation: generate a new `kid`, send the new public key, switch signing, then ask IMBA to revoke the old `kid`

Questions during onboarding: reply on the same support thread or write again to [support@imbawallet.com](mailto:support@imbawallet.com).