Skip to main content

API key generation

The PaymentsAI Public API authenticates with an API key in the Authorization: ApiKey ... header (see Authentication). This page covers how to obtain that key, the temporal-to-permanent exchange that happens on production, and how to rotate the key over time.

Stage vs production​

The flow differs between environments:

  • Stage: Your integration consultant delivers a ready-to-use API key via 1Password. There is no temporal-to-permanent exchange on stage. Plug the key into your API_KEY environment variable and start integrating.
  • Production: You receive a temporal API key via 1Password and use it once to generate your permanent API key through the exchange described below. The temporal key is automatically deleted after a successful exchange.

For the broader go-live procedure (Stage 0 to Stage 5), see the Integration checklist & Go-Live runbook.

Production: Temporal to permanent exchange​

Step A: Obtain the temporal API key​

The solution architect delivers a secure 1Password link with the temporal API key and the Account ID. If the API key field is non-selectable in 1Password, triple-click it to select the entire value.

The temporal API key is valid for 7 days. If you do not use it within that window, the key expires and PaymentsAI must issue a new one.

Step B: Exchange the temporal key for a permanent key​

A single PATCH request against the production API sets the account secret and returns the permanent API key in the response body.

Export the values you received so the request below can reference them:

export ACCOUNT_ID="Your Account ID Here"
export TEMPORAL_API_KEY="Your Temporal API Key Here"

Then run the exchange:

curl --location --request PATCH \
  "https://api.payments.ai/v1/accounts/public-api/${ACCOUNT_ID}" \
  --header "Authorization: ApiKey ${TEMPORAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{ "secret": "YOUR_CHOSEN_SECRET" }'

The permanent API key is returned in the response body. The Authorization header for future requests uses this format:

Authorization: ApiKey <accountId>_<apiKey>_<apiKeyId>

The separator is an underscore (_). See Authentication.

After this exchange:

  • The temporal API key is automatically deleted and cannot be reused.
  • PaymentsAI does not store or log the permanent API key or the secret. Save both in a secure location immediately. There is no recovery option if either is lost.

The same endpoint exists on stage under https://staging-api.payments.ai/v1/accounts/public-api/${ACCOUNT_ID}, but on stage the API key is delivered ready-to-use and the exchange is skipped.

Secret policy​

Your account secret must meet all of the following criteria:

  • Between 12 and 30 characters.
  • At least one uppercase letter.
  • At least one alphanumeric character (letter or number).

The secret must be rotated every 90 days. The new secret must be different from the last 4 secrets used.

Key rotation​

Two endpoints support key management after the initial exchange.

Retrieve the API key after rotation:

curl --location --request PUT \
  "https://staging-api.payments.ai/v1/accounts/public-api/${ACCOUNT_ID}/api-keys" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ApiKey ${API_KEY}' \
  --data '{ "secret": "YOUR_CURRENT_SECRET" }'

Rotate the API key with a new secret:

curl --location --request PATCH \
  "https://staging-api.payments.ai/v1/accounts/public-api/${ACCOUNT_ID}/api-keys/${API_KEY_ID}" \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ApiKey ${API_KEY}' \
  --data '{ "secret": "YOUR_NEW_SECRET" }'

Replace staging-api.payments.ai with api.payments.ai for production environments.

After exchange: What to store​

Persist all three parts of the key plus the Account ID and Organization ID in your backend secrets manager:

ValueWhere it comes from
accountIdDelivered by the solution architect.
apiKeyReturned in the exchange response (Step B).
apiKeyIdReturned in the exchange response (Step B).
Account secretChosen by you in Step B. Needed for future rotation.
organizationIdPAI panel → Settings → General → Organization information.

See Account structure for what each ID represents.