Authorization

Create or renew a test API key (Sandbox only)

post

https://api-stage.novapost.com/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.com/
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"
  }
}

Generate a temporary JWT-token

get

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

/clients/authorization

Issues a temporary JWT-token for making authorized API requests. A valid apiKey must be provided as a query parameter.

How to obtain an apiKey:

• In Sandbox, use POST /test-api-keys with a registered phone number from the Client Portal (EBC): https://my.novapost.com/

• In PROD, use your personal apiKey provided by your manager

Usage:

• Call GET /clients/authorization?apiKey={apiKey}

• On success, copy the jwt from the response

• Open the Authorize dialog in this documentation, select the JWT scheme, and paste the jwt

• All Try-it-out requests will then automatically include Authorization: {jwt}

Notes:

• The jwt is valid for ~1 hour; request a new one after expiry

• Do not store jwt beyond its TTL

• The /test-api-keys route is not available in PROD

🔹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.

Query parameters

apiKeystringRequired

To utilize this method, a personal API key is required.

Responses

200

JWT-token

application/json

jwtstring · jsonOptional

Personal JWT-token, expires after one hour to prevent any fraud, requiring a new request to generate a fresh token.

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJucCIsImlhdCI6MTY4NTYyNzQxNCwiZXhwIjoxNjg1NjMxMDE0LCJjaWQiOiI1YzQxMmUzYS01ODY4LTQ4YjktYTYwYS0wZTAzOTI4NGVjNDYiLCJyZWYiOiI2NDI0NmRkMzg0ZWI3Yzg2MmMwMzg3YzAifQ.MmhM9rHCYItjA5a7B9PtrdKUKRiHhN43UotWKtKjt78

401

Unauthorized

application/json

422

Validation error

application/json

503

Connection time-out

application/json

get

/clients/authorization

HTTPcURLJavaScriptPython

GET /v.1.0/clients/authorization?apiKey=text HTTP/1.1
Host: api-stage.novapost.com/
Accept: */*

{
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJucCIsImlhdCI6MTY4NTYyNzQxNCwiZXhwIjoxNjg1NjMxMDE0LCJjaWQiOiI1YzQxMmUzYS01ODY4LTQ4YjktYTYwYS0wZTAzOTI4NGVjNDYiLCJyZWYiOiI2NDI0NmRkMzg0ZWI3Yzg2MmMwMzg3YzAifQ.MmhM9rHCYItjA5a7B9PtrdKUKRiHhN43UotWKtKjt78"
}