Skip to content
Last updated

Overview

The following sections describe the authentication mechanisms and headers that are used for NPS APIs.

While you can get started by just setting a few header values listed below, the NPS system is full-featured and comprehensive. View the full set of API Standards to learn more.

Required Headers

The following headers are required for all APIs.

Header
Type
Description
Content-TypestringUsed by the client to indentify what is being sent to the API.
application/json
AuthorizationstringUsed by the API to authenticate all requests received. Either of these options will apply:
Basic <Base64_encoded_string>
Bearer <JWT>

Basic Authentication

Note: Basic Authentication functionality will be deprecated and is limited to specific APIs.

Getting Started with API Authentication

  1. Obtain Credentials
    Contact the NPS Client Services team to receive a private key and passphrase for a specific merchant.

  2. Send the Authorization Header
    Combine the Base64 encoded private key and passphrase in the Authorization HTTP header.

Header Creation Steps

  1. Combine the private key and passphrase with a colon (:).
    Example: Test Merchant:test123

  2. Base64 encode the resulting string.
    Example: VGVzdE1lcmNoYW50OnRlc3QxMjM=

  3. Include the Base64 encoded string in the Authorization header using the Basic scheme.

Authorization: Basic VGVzdE1lcmNoYW50OnRlc3QxMjM=

Bearer Authentication

NPS grants API access using an API Key ID embedded in a one-time JWT token.

Getting Started with API Authentication

  1. Obtain Credentials
    Contact the NPS Client Services team to receive API Key ID and API Key credentials for the desired NPS service.

  2. Create JWT
    JWT Creation steps with claims information is provided below.

  3. Include the one-time JWT in the Authorization header with the Bearer scheme.
    Example: Authorization: Bearer <token>

JWT Creation Steps

  1. API Key ID
    Use the API Key ID as the JWT "sub" (subject).

  2. Timestamp (Issue At)
    Use the current timestamp as the JWT "iat" (issued at).

  3. JWT Expiration (Optional)
    You can optionally include the JWT "exp" (expiration) claim. By default, the expiration is configured when the API Key is created.

  4. HMAC SHA-512
    Use the HMAC SHA-512 algorithm for signing the JWT.

  5. API Key (Secret)
    Use the API Key as the secret for signing the JWT.

How to Use JWT

To make an API request, include the JWT token in the Authorization header using the Bearer scheme:

Authorization: Bearer <token>

Important Notes

  • Ensure that the JWT Expiration (exp) is within the expiration window set when the API Key was created. If the expiration exceeds the allowed window, the request will be denied.
  • Always securely store your API Key and API Key ID. Never expose your secret key in client-side code.
Previous page
Next page