API Key Generation

API keys are issued exclusively to individuals (natural persons).

To use the API for business purposes, you must designate an authorized company representative and generate API keys in their name, or assign as the authorized representative a person who already has an existing API key.

The authorized representative’s details must be specified in the contract with Nova Post.

How to create a key for a European client

1. Create an account in the My Nova Post cabinet

Register at my.novapost.com. Step-by-step registration instructions

1. Affiliate an individual to the organization

   1. Write an email to the NovaPost sales manager.

   2. In the letter, provide the tax code and the name of the organization, details of the individual: full name, phone number, email.

   The details of the individual must match those for which the account in the My Nova Post cabinet was or will be registered.

When registering, use the phone number and email address of the authorized representative specified in the contract. If an account has already been created, re-registration is not required.

1. Create an API key in your My Nova Post account. Go to the “Integrations → API Keys” section at my.novapost.com and create a key for the production environment.

When creating a key, the system will automatically display all organizations assigned to your account. You can:

• select one or more organizations to which access is granted through this key;

• or create separate keys for each organization if you need to divide access between teams or projects.

The key immediately appears in the list of information about:

• creation date

• name

• status (active/deactivated)

• organization

• validity period

How to Create a Test API Key - method 1

On the test key generation page in the Nova Post portal:

• Enter the phone number registered in your My Nova Post account (my.novapost.com) and submit a request to generate the key.

• After a successful request, a test API key for the sandbox (Stage environment) will be generated. The key will be linked to an individual (natural person) and will not be associated with any organization. Generate a test key

Method 2

Create or renew a test API key (Sandbox only)

post

https://api-stage.novapost.pl/v.1.0https://api.novapost.com/v.1.0

/test-api-keys

Public endpoint available only in non-production environments (Sandbox) to create or renew a test API key for a client identified by phone.

Requirements:

• The phone number must be registered in the Client Portal (EBC): https://my.novapost.com/

• UA key generation is currently not supported

Behavior:

• If a key already exists and is Active, a repeated call within the same day will return the same key

• If expired, the key will be reactivated with a new expiration date

• If deleted by cleanup, a new key will be created

• Only one active key is allowed per phone, limited to one request per day

Next step: After receiving the apiKey, you must generate a temporary JWT by calling GET /clients/authorization. The JWT is required for all authorized requests. Paste the jwt into the Authorize dialog under the JWT scheme in this documentation to enable Try-it-out.

🔹Description of control elements:

SCHEMA Displays the full technical structure of the request or response, including field names, data types, required fields, allowed values, and validation rules.

• Single line description A description that fits into a single line; any text that does not fit remains hidden.

• Multiline description An expanded description that displays more than one line of text.

EXAMPLE Shows a ready-made sample JSON with correctly formatted values to demonstrate how a valid request or response should look.

Body

application/json

phonestringRequired

Phone number registered in EBC. Format like 49XXXXXXXXX (no '+'). UA keys generation is currently not supported.

Example: 498213437654

Responses

200

Test API key created or returned

application/json

apiKeystringRequired

Test API key for Stage usage only.

Example: 99dde7bdce11414efc2f1c10ddbfd42da8ce4bf2

createdAtstring · date-timeRequiredExample: 2025-08-27T08:03:02.000000Z

expDatestring · date-timeRequiredExample: 2026-08-29T23:59:59.000Z

statusstring · enumRequiredExample: ActivePossible values:

400

Validation error

application/json

404

Client not found in EBC

application/json

409

Multiple matching clients found in EBC

application/json

429

Daily limit exceeded for this user (one request per day)

application/json

503

Connection time-out

application/json

post

/test-api-keys

HTTPcURLJavaScriptPython

POST /v.1.0/test-api-keys HTTP/1.1
Host: api-stage.novapost.pl/
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "phone": "498213437654"
}

{
  "value": {
    "apiKey": "78b97003b587d7758bede604fd185e3e",
    "createdAt": "2025-07-24T09:00:00Z",
    "expDate": "2026-07-24T23:59:59Z",
    "status": "Active"
  }
}

How to create a key for a client from Ukraine

Generate keys in the Business account in Ukraine under the "Settings - Security" section. Direct link to the section.

1. Log in to the business cabinet at new.novaposhta.ua as a legal entity.

1. Go to the "Settings" section.

1. Select the "Security" section.

1. Click "Create key"

5. The key has been created. Copy the code for using the Nova Post API.

Additional Recommendations

Security: Store your API keys securely and do not share them with third parties.

Testing: Use the sandbox environment to validate your integration before moving to production.

Access Control: Regularly review the list of users who have access to your account and API keys.Additional Recommendations