> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key.md).

# Reset Terminal API Key

Issues a new payments API key for an existing terminal. This is the only way to obtain a usable terminal payments API key after the terminal has been created, including for the default terminals Bead creates at boarding. The call returns the updated terminal record with the new key.

Use the reset call when:

* you need the key for a terminal Bead created at boarding
* you did not capture the key when you created a terminal
* you need to replace a suspected exposed key

{% hint style="warning" %}
**Resetting replaces the previous key immediately.** There is no overlap window. Any system still using the old key receives `401 Unauthorized` as soon as the reset completes.

* Reset only when no system depends on the current key, or when you are ready to update every system that does.
* The reset response is the only place the new key is returned. Store `apiKey.secret` before you do anything else with it.
* Do not blindly retry a reset after a timeout. A second reset invalidates the key from the first one. Confirm the outcome of the first call before you reset again.
  {% endhint %}

### Endpoint

| Action                     | Endpoint                                                        |
| -------------------------- | --------------------------------------------------------------- |
| Reset the terminal API key | `POST https://api.test.devs.beadpay.io/Terminals/{id}/api-keys` |

### Authentication

Use your **admin API key** in the request header for terminal management operations.

### Request headers

| Header      | Value              |
| ----------- | ------------------ |
| `X-Api-Key` | `{adminApiKey}`    |
| `Accept`    | `application/json` |

### Path parameter

| Name | Type   | Description                                                                                                                                                                                                                                                                                                                                           |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Terminal identifier returned by [Create Terminal](https://developers.bead.xyz/entity-management/terminal-management/create-terminal.md), [List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals.md), or [Get Terminal](https://developers.bead.xyz/entity-management/terminal-management/get-terminal.md). |

### Request

This endpoint does not require a request body.

#### Example request

```bash
curl --request POST "https://api.test.devs.beadpay.io/Terminals/67f10123456789abcdef0456/api-keys" \
  --header "X-Api-Key: {adminApiKey}" \
  --header "Accept: application/json"
```

#### Example response

```json
{
  "id": "67f10123456789abcdef0456",
  "name": "Front Counter 1",
  "description": "Primary checkout terminal",
  "merchantId": "67e90123456789abcdef0001",
  "merchantStatus": "active",
  "type": "virtual",
  "merchantLocationId": "67f00123456789abcdef0123",
  "merchantLocation": {
    "id": "67f00123456789abcdef0123",
    "name": "Main Store",
    "address": {
      "address1": "123 Main St",
      "city": "Boston",
      "region": "MA",
      "country": "US",
      "postalCode": "02110"
    },
    "isEnabled": true
  },
  "displayLogo": true,
  "webhookUrl": "https://example.com/webhooks/terminal/67f10123456789abcdef0456",
  "isEnabled": true,
  "extendRedirectUrl": false,
  "tenderTypes": ["ethereum", "usdcBase"],
  "created": "2026-04-02T15:00:00Z",
  "updated": "2026-04-03T11:20:00Z",
  "maxTransactionAmount": 5000,
  "apiKey": {
    "secret": "pk_test_new_terminal_secret_value",
    "maskedSecret": "pk_****_value"
  },
  "useSandboxSharedWallet": true
}
```

### What to do after reset

After resetting the key:

1. Store the new `apiKey.secret` securely.
2. Update any backend service, secret manager, or environment configuration that uses the prior terminal payments API key.
3. Use the new terminal payments API key in the `X-Api-Key` header for future Payments API requests.
4. Do not use `apiKey.maskedSecret` for authentication.

Payments authentication is header based and uses the full terminal API key. The masked value is display only.

### Read endpoints do not return the key

[Get Terminal](https://developers.bead.xyz/entity-management/terminal-management/get-terminal.md) and [List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals.md) return only `apiKey.maskedSecret`. Do not build a flow that expects to read the usable key back from a terminal record. The same applies to `GET /Terminals/{id}/api-keys`, which is listed in the API reference but does not return a usable key to API key callers. To obtain a key, use the reset call on this page.

### Field notes

| Field                 | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| `id`                  | Terminal identifier.                                                          |
| `apiKey.secret`       | New terminal payments API key. Store securely and use for Payments API calls. |
| `apiKey.maskedSecret` | Masked display value only. Not valid for authentication.                      |
| `updated`             | UTC ISO-8601 timestamp reflecting the terminal update after key reset.        |

### Notes

* Use your **admin API key** for these terminal management operations.
* Use the terminal payments API key for payment activity performed by that terminal.
* Treat `apiKey.secret` like a password and avoid logging or exposing it in client-side code.
* Resetting replaces the previous key, so update every system that uses the old key.

### Response codes for reset

| Code  | Meaning                                                                      |
| ----- | ---------------------------------------------------------------------------- |
| `200` | Terminal API key reset successfully.                                         |
| `201` | Terminal API key reset successfully and returned as a created response.      |
| `202` | Reset accepted for processing.                                               |
| `400` | The request was invalid.                                                     |
| `401` | The admin API key is missing or invalid.                                     |
| `403` | The caller is authenticated but not permitted to reset the terminal API key. |
| `409` | A conflicting terminal state prevented key reset.                            |

### Related operations

* [Create Terminal](https://developers.bead.xyz/entity-management/terminal-management/create-terminal.md)
* [List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals.md)
* [Get Terminal](https://developers.bead.xyz/entity-management/terminal-management/get-terminal.md)
* [Update Terminal](https://developers.bead.xyz/entity-management/terminal-management/update-terminal.md)
* [Delete Terminal](https://developers.bead.xyz/entity-management/terminal-management/delete-terminal.md)
* [Webhook Management](https://developers.bead.xyz/entity-management/terminal-management/webhook-management.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
