Create a customer API key (by external customer id)

POST

https://api.agentpaid.io/api/v2/customers/external/:externalId/api-keys

POST

/api/v2/customers/external/:externalId/api-keys

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.customers.createCustomerApiKeyByExternalId({
        externalId: "customer_123",
        body: {
            name: "Tenant runtime (production)",
        },
    });
}
main();

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "Tenant runtime (production)",
  "description": "Used by the production tenant service to report usage signals",
  "customerId": "cus_abc123",
  "customerExternalId": "customer_123",
  "scopes": [
    "write:usage"
  ],
  "keyPrefix": "paid_ck_live_3f9",
  "last4": "q7Zk",
  "status": "ACTIVE",
  "createdAt": "2025-03-15T10:00:00Z",
  "lastUsedAt": null,
  "expiresAt": "2027-09-25T00:00:00Z",
  "revokedAt": null,
  "key": "paid_ck_live_3f9aQ7…q7Zk"
}

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. Addresses the customer by your external customer id.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Path parameters

externalIdstringRequired>=1 character

Customer ID from your system, stored on Paid as the customer’s externalId.

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