Skip to main content
This page discusses key concepts for integrating with CPN. Understanding these concepts can help you integrate with CPN more effectively.

​
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
curl --location --request GET 'https://api.circle.com/v1/cpn/payments' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

​
Security notes

  • Your API key provides full access to the CPN API, so make sure they are stored securely. They should never be exposed in public repositories and they should only be shared within your organization using secure methods. As a best practice, you should 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.