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

# Create API Key (Create / Edit)

> The merchant dashboard Developers > API Keys > New page — a full-screen form to create a new API key by entering a key name, an optional IP allow list, and selecting read/write scope permissions; the secret key is shown once after creation. Editing an existing key (name/IP/permissions) uses the same layout.

## What this is

This is the **create key flow** of the **API Keys** page under the **Developers** module (page title "Create API Key"). Reached by clicking **Create API Key** at the top right of the API Keys list, it's a full-screen form: the left side has **Key details** (key name, IP allow list), the right side has **Scope permissions** (read/write per resource), and **Create** at the bottom completes it. API keys are used to call UQPAY APIs programmatically (server-to-server); anyone holding the key can call your API within the permissions you grant it. Use this same layout page both to create a new key and to **edit** an existing key's name, IP allow list, or permissions.

## Steps

**Create a new key:**

1. In the left nav, go to **Developers**, then open **API Keys**.
2. Click **Create API Key** at the top right to open the full-screen creation page.
3. Fill in **Key Name** (required): give the key a name that's easy to identify (e.g. "Production API Key").
4. (Optional) Fill in **IP Allow List**: restrict calls to only the IPs you specify. Enter an IPv4 or IPv6 address (CIDR masks supported, e.g. `10.0.0.0/24`, `2001:db8::/32`), press **Enter** or **comma** to add it, or **paste** a batch to add several at once; suggested common ranges pop up as you type — use the arrow keys to select and Enter to confirm. Added entries show as tags; click the "x" on a tag to remove it. Leave it empty for no source IP restriction.
5. In the **Scope permissions** section on the right, check the permissions this key needs. Permissions are grouped by resource, one row per resource with **Read** and **Write** checkboxes: check Read for read-only access, check Write if write access is needed (checking Write automatically checks Read too). Use the column checkbox at the top of a group for one-click "Read all / Write all", or a resource group's "select all" to bulk-check it; you can also use **Select all** / **Clear all** at the top right for the whole page. **At least one permission is required**, or the key can't be created.
6. Once everything looks right, click **Create** at the bottom. If no permission is selected, you'll see "Select at least one scope."; if the name is empty, you'll be prompted to fill it in.
7. The system may require **two-factor verification** during creation (account password, or an authenticator code / passkey) — complete it in the dialog.
8. After creation succeeds, you land on the key display page showing "API Key Created", along with the key's **secret key**. Click the eye icon to show/hide the plaintext, and the copy button to copy it. **The secret is shown only this once** — copy and save it immediately, then click **Done, I've saved my key** to return to the list.

**Edit an existing key:**

1. On the API Keys list, open the **⋯** menu at the end of the key's row → **Edit API Key** to open the same-layout edit page.
2. The edit page shows the key's **Client ID** (read-only, cannot be changed) at the top left; below it you can change Key Name and IP Allow List, and Scope Permissions on the right.
3. Click **Save Changes** at the bottom when done. Editing may also trigger two-factor verification. Editing does **not** regenerate the secret key (a successful save won't show the key again).

## Fields and statuses

**Key details (left column):**

| Field         | Meaning (merchant view)                              | Notes                                                                               |
| ------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Key Name      | The identifying name for this key                    | Required                                                                            |
| IP Allow List | The list of source IPs allowed to call with this key | Supports IPv4 / IPv6, with optional CIDR mask; empty means no source IP restriction |
| Client ID     | The key's client identifier (edit page only)         | Read-only, cannot be changed                                                        |

**Scope permissions (right column):** grouped by resource, each resource can be granted **Read** (read-only) and **Write** (write access) independently. Grant only the permissions this key actually needs — you can adjust later on the edit page. Related controls:

| UI element                                 | Meaning                                                                                                                 |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Read / Write                               | Per-resource read/write checkboxes; checking Write automatically checks Read too                                        |
| Read all / Write all                       | One-click check for an entire column within a resource group                                                            |
| Select all (within a group)                | Checks all read/write permissions for one resource group                                                                |
| Select all / Clear all (top right of page) | One-click check or clear of all permissions on the page                                                                 |
| View API docs / View covered endpoints     | Opens the API docs for that resource, or shows which endpoints that permission covers, to help you decide what to grant |

> The bottom of the page shows a live count: the current key name and "N scopes selected."

**Secret key display (after successful creation):** shows the full secret string for this key, shown only once, with the page notice "This secret key will only be shown once" and "Store it securely. You won't be able to view it again after closing this dialog."

## Edge cases and troubleshooting

* **No "Create API Key" entry point**: either your account lacks write permission for API keys (ask an admin to grant it), or your account hasn't enabled the OpenAPI capability yet (not activated) — the entry point won't show until an account manager/admin activates it.
* **Clicking "Create" shows "Select at least one scope."**: nothing is checked under **Scope permissions** — check at least one resource's Read or Write and submit again.
* **Can't enter an IP / "Invalid IP address" message**: only valid IPv4 or IPv6 is accepted (CIDR allowed, e.g. `10.0.0.0/24`, `2001:db8::/32`) — check the format and retry.
* **"IP already added" message**: that IP is already in the allow list, no need to add it again.
* **Allow list contains `0.0.0.0/0` or `::/0`**: this allows calls from any source IP; the page shows the safety notice "This key will accept calls from any IP" — recommended only for short-term testing, narrow it to your server IPs for production.
* **Didn't copy the secret in time / forgot to save it**: the secret is shown only once at creation and can't be viewed again afterward, nor regenerated via edit — delete the key and create a new one.
* **A password or code prompt pops up when creating / saving**: this is two-factor verification for creating/modifying a key — enter your account password or authenticator code/passkey as prompted to continue; closing the dialog cancels the action without it counting as a failure.
* **The edit page bounces back to the list right after opening**: editing requires entering via the list's "⋯" menu so the target key's context is carried over; a direct refresh or link visit lacks that context and returns to the list automatically — go back to the list and use "Edit API Key" again.

## Common questions (Q\&A)

* **Q: How do I create an API key?** A: Developers > API Keys > "Create API Key" at the top right, enter a name → (optionally) an IP allow list → check read/write permissions → click "Create", then copy the displayed secret immediately.
* **Q: What's required to create a key?** A: Key name is required, and at least one permission must be selected; IP allow list is optional.
* **Q: How do I fill in the IP allow list? Is it required?** A: It's optional. Enter one or more IPv4/IPv6 addresses (CIDR masks allowed, e.g. `10.0.0.0/24`, `2001:db8::/32`), press Enter or comma to add, or paste a batch; leave it empty for no source IP restriction.
* **Q: How do I choose scope permissions? What's the difference between Read and Write?** A: Check per resource — Read is read-only, Write is write access; checking Write automatically includes Read. Grant only the minimum permissions the key needs.
* **Q: Where do I see the secret key after creation? Can I view it again?** A: The success page shows the full secret key once — copy and save it right away. It can't be viewed again after closing, and it can't be regenerated; if lost, delete the key and create a new one.
* **Q: How do I change an existing key's name / IP / permissions?** A: Open the "⋯" menu on that row in the list and choose "Edit API Key", then change the name, IP allow list, or scope permissions and click "Save Changes".
* **Q: Does editing a key generate a new secret?** A: No. Editing only changes the name, IP, or permissions — it never regenerates the secret.
* **Q: Can I change the Client ID?** A: No, the Client ID is read-only and is shown only on the edit page, so you can confirm which key you're editing.
* **Q: Why don't I see the "Create API Key" button?** A: Usually a missing write permission for API keys, or the account hasn't activated OpenAPI capability — contact an admin to grant permission or activate it.
* **Q: Why am I asked to re-enter my password / a code when creating?** A: This is two-factor verification for key creation — enter your account password or authenticator code/passkey in the dialog.
* **Q: Is there a risk in setting the IP allow list to 0.0.0.0/0?** A: Yes — it allows any IP to call. The page notes this is recommended only for short-term testing; narrow it to your server IPs for production use.
* **Q: Which endpoints can a key call / what does a permission cover?** A: Click the info icon next to a resource in Scope permissions to "View covered endpoints", or click "View API docs" for that resource's documentation.