# Reset Terminal API Key

Resets the payments API key for an existing terminal and returns the updated terminal record with the new terminal API key.

Use this endpoint when you need to rotate a terminal credential, replace a suspected exposed key, or issue a fresh key for backend payment requests.

### Endpoint

`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, List Terminals, or Get Terminal. |

### Request body

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.

### 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 rotation.     |

### Notes

* Use your **admin API key** for this terminal-management operation.
* Use the returned **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.
* This endpoint is intended for credential rotation and operational maintenance.

### Response codes

| 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)
* [List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals)
* [Get Terminal](https://developers.bead.xyz/entity-management/terminal-management/get-terminal)
* [Update Terminal](https://developers.bead.xyz/entity-management/terminal-management/update-terminal)
* [Delete Terminal](https://developers.bead.xyz/entity-management/terminal-management/delete-terminal)
* [Webhook Management](https://developers.bead.xyz/entity-management/terminal-management/webhook-management)