Preczn uses API keys to authenticate every request to the platform. Each key has a type (public or private) and a mode (test or live), which together determine what the key can access and in which environment.

Key Types and Modes

Every API key is one of four variants based on its type and mode:

All keys follow the format {prefix}{26-character identifier}. For example:

pub_test_01h9kp4q6b7r3m8n5v2w1x0y4z
priv_01h9kp4q6b7r3m8n5v2w1x0y4z

Public vs Private Keys

This is the most important distinction in the Preczn key model. Choosing the wrong key type will either block legitimate requests or expose sensitive operations to client-side code.

Public Keys

Public keys are used for client-side tokenization — they allow your frontend to securely collect payment information without sensitive data ever touching your server.

Your public key is passed to the Preczn Hosted JavaScript Clients to load the tokenization resources your integration needs:

Each client uses your public key to tokenize the customer's payment method into a single-use token. Your backend then uses a private key to process the transaction with that token.

<script src="https://api.preczn.com/v1/clients/preczn.min.js?publicApiKey=pub_test_01h9kp4q6b7r3m8n5v2w1x0y4z"></script>

📘

Why public keys are safe to expose

Public keys can only create single-use tokens. They cannot read transaction data, manage merchants, access vault tokens, configure webhooks, or perform any other operation. Even a compromised public key cannot access sensitive data or modify your account.

Private Keys

Private keys are designed for server-to-server communication. They have full access to the Preczn API, including:

• Processing transactions (sale, authorize, capture, void, refund)
• Managing tokens, including multi-use vault tokens
• Merchant CRUD operations
• Webhook management
• Compliance and SAQ operations
• Client session creation
• BIN lookup
• Merchant onboarding operations

❗

Never expose private keys

Private keys must never appear in client-side code, HTML source, JavaScript bundles, mobile apps, or public repositories. Treat them with the same care as a database password. If you suspect a private key has been exposed, deactivate it immediately and generate a replacement.

Quick Comparison

Authentication

Server-Side Requests (Private Key)

Pass your private key in the x-api-key HTTP header on every request:

POST /v1/transactions HTTP/1.1
x-api-key: priv_test_01h9kp4q6b7r3m8n5v2w1x0y4z
Content-Type: application/json

{
  "merchantId": "mid_01h9kp4q6b7r3m8n5v2w1x0y4z",
  "amount": 2500,
  "payment": {
    "token": "tkn_01h9kp4q6b7r3m8n5v2w1x0y4z"
  }
}

Client-Side Tokenization (Public Key)

Your public key is passed as a publicApiKey query parameter when loading the Hosted JavaScript Clients. The clients handle tokenization automatically — you do not need to make direct API calls with your public key. See the Public Keys section for supported clients and integration links.

Authentication Errors

Test Mode vs Live Mode

Every API key operates in exactly one mode, determined at creation and immutable afterward.

Test mode keys can only access test mode resources (merchants, transactions, tokens, webhooks). Live mode keys can only access live mode resources. There is complete isolation between modes — a test key will never see live data, and a live key will never see test data.

🚧

Mode cannot be changed

Once a key is created in test or live mode, that mode cannot be changed. To switch modes, create a new key in the desired mode.

Managing Keys in the Dashboard

Default Keys

When a new platform is created, Preczn automatically generates two test mode keys:

These keys are ready for development immediately. You can rename, deactivate, or delete them at any time.

Creating a New Key

1. Navigate to API Keys in the left-hand dashboard navigation.
2. Select +Generate New Key.
3. Enter a name for the key (3-25 characters) and choose whether the key is public or private.
4. Select Generate Key.

The key is active immediately upon creation.

🚧

Copy your key

Make sure to copy the full key value when it is displayed. For security, the complete key may not be shown again after you navigate away.

Activating and Deactivating Keys

You can toggle any key between active and inactive status at any time from the API Keys page. Inactive keys will be rejected by the API with a 401 Unauthorized response.

Deleting Keys

Deleted keys are permanently removed and cannot be recovered. Before deleting a key, confirm that no active integrations depend on it.

Key Rotation

Preczn API keys do not expire automatically — they remain valid until you deactivate or delete them. Preczn recommends rotating keys regularly to reduce the impact of a compromised credential.

Rotation steps:

1. Create a new key of the same type and mode.
2. Update your integration to use the new key.
3. Verify the new key works correctly in your environment.
4. Deactivate or delete the old key.

👍

Best practices

• Rotate keys on a regular schedule.
• Create unique keys for each integration or service (e.g., separate keys for your web app and your batch processing system).
• Never share keys across test and live environments — they are separate by design.
• Store keys in environment variables or a secrets manager, never in source code.