Skip to navigation
API Referencecustomers

Create a customer API key

Creates an API key bound to this customer. The response carries the secret in key, returned only this once: store it immediately, as Paid keeps only its hash. The key acts for this customer alone: it can send signals for this customer through POST /api/v2/signals/bulk, and every other route refuses it. Requires write:api-keys, which full-access keys hold; a restricted key needs the scope granted explicitly. Use the value returned as customer.id, for example cus_abc123; if you have your own customer ID, use the /api/v2/customers/external/{externalId}/… twin.

Authentication

AuthorizationBearer
API Key authentication using Bearer token

Path parameters

idstringRequiredformat: "^cus_.+"
Paid customer display id

Request

Body
namestringRequired1-255 characters
A label for the key, shown in lists and in the audit log.
descriptionstringOptional<=1000 characters
Optional free text about where the key is used.
expiresAtdatetimeOptional

Optional expiry (ISO 8601), which must be in the future. Without it the key works until it is revoked.

Response

201
idstringformat: "uuid"
The key's id.
namestring
descriptionstring or null
customerIdstring or null

Display id (cus_…) of the customer the key acts for.

customerExternalIdstring or null
That customer's id in your system, if it has one.
scopeslist of strings
What the key may do.
keyPrefixstring
The key's first characters, to recognise it in a list.
last4string
The key's last four characters.
statusenum

ACTIVE until the key is revoked (REVOKED) or its expiry passes (EXPIRED).

Allowed values:
createdAtdatetime
lastUsedAtdatetime or null
expiresAtdatetime or null
revokedAtdatetime or null
keystring

The secret. Returned only in this response and never again: store it now. Paid keeps only its hash.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error