Skip to main content
Every CPN integration depends on two concepts: authenticating requests with your API key, and using idempotency keys to prevent duplicate payments and transactions.

Authentication

CPN authenticates your API requests using a unique key associated with your account. All authentication is performed in the HTTP header of requests to the API. If a key is not provided, or an incorrect key is provided, the API returns a 401 - Invalid Credentials error. All requests must use HTTPS; the API rejects any requests using plain HTTP. Circle provides API keys for authentication with the CPN API. These keys are provided manually during onboarding. The following is an example of how to set up the authentication header:
Shell
Circle Console credentials don’t work with CPN. If your organization isn’t provisioned for CPN, the API can return a 401 error even with a valid key. To request access, ask your Circle account team for an onboarding invitation to the Circle hub, or test first in the Circle hub sandbox.

Security notes

  • Your API key provides full access to the CPN API. Store it securely, never expose it in public repositories, and share it only through secure methods in your organization. As a best practice, rotate your API keys periodically.
  • When setting up your API key with Circle, you can request that only certain IP addresses be allowed to make API calls using the key. Talk to your Circle representative about establishing an IP allowlist for your API key.
  • You should ensure that API requests are always made over TLS/encrypted connections to prevent the exposure of your key.
  • For webhook subscriptions, you must provide an HTTPS endpoint, and validate the signature with Circle-provided public keys.

Idempotency

For endpoints that create transactions and payments, CPN requires an idempotency key to be included in the request body. The idempotency key must be in the UUID v4 format. This allows the API to identify if a repeated request is unique or duplicate, and prevent unintended duplicate transactions. To generate an idempotency key, use a UUID generator in your selected programming language. Generated UUIDs can then be passed to the API as idempotency keys.