---
title: "Issue API Key"
method: POST
path: "/v1/keys"
tags: ["Payment SDK API Key Management"]
---

# Issue API Key

`POST /v1/keys`

## Request

- Base URL: `https://api.cloudbeds.com/payments/sdk-api`
- URL: `https://api.cloudbeds.com/payments/sdk-api/v1/keys`
- Auth: HTTP bearer

Issue a new API key for the Payment Element, scoped to one or more properties.

The response includes both the **identity** (public) and the **secret** (private).
The secret is **only returned once** at creation time and cannot be retrieved later.

> **Important:** Treat the `secret` as a password. Store it in a secure vault or secrets manager.
> Do not log it, commit it to source control, or expose it in client-side code.

## Using with the Payment Webcomponent

To initialize the payment webcomponent your backend must produce a token from the
`identity` and `secret`, then populate the webcomponents `api-key` field.
The token format is:

```
{identity}.{base64(HMAC_SHA256(message, secret))}
```

Where:

- **`message`** is the literal string `"{identity}|{property_id}"` (UTF-8 bytes, pipe-separated, no surrounding whitespace).
- **`secret`** is the value returned by this endpoint, used **as-is** (its raw ASCII bytes). Do **not** base64-decode it before signing.
- The HMAC digest is the **raw 32 bytes** of HMAC-SHA256, then **standard base64** encoded (not base64url, no `=` stripping).
- The token is the `identity`, a literal `.`, then the base64 digest.

## Request body

- IssueKeyRequest: Issue Api Key
  - `property_ids` string[], required: Array of property IDs to scope the key to. At least one is required and must be scoped to your JWT key

## Response `201`

Successful operation

- IssueApiKeyResponse: Issue Api Key Response
  - `identity` string, required: Public key identifier (e.g. pek_a1b2c3d4e5f6g7h8i9j0k1l2).
  - `secret` string, required: Private key secret. Only returned once at creation. Store securely and never expose publicly.
  - `property_ids` string[], required: Property IDs the key is scoped to.
  - `status` string, required: Key status.
  - `created_at` string, date-time, required: ISO 8601 creation timestamp.

## Other responses

- `400`: Malformed request body or validation failure
- `401`: Missing or invalid JWT token
- `403`: Insufficient permissions for the requested property IDs
- `500`: Internal server error

---

[API](https://skmtc.dev/cloudbeds/apis/payment-sdk-api.md) - [All operations](https://skmtc.dev/cloudbeds/apis/payment-sdk-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudbeds/apis/payment-sdk-api/revisions/afe699ad0227?raw)