We use API Keys to ensure the security of your sensitive data, which is transmitted via Secure Sockets Layer (SSL) over the HTTPS protocol.
API Key Authentication
For REST authentication the following HTTP headers in each HTTP request targeted are required.
Mandatory API Key authentication basic:
- Template: “Authorization: Basic {Base64(API_KEY:)}”
- Example
- With the following given APIKey =
bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686
- We encode this in base 64:
bb09c2b6a9478720765c757a8bcadf1aa1fb31554566a21118c9c75e26c29686:
(note that the colon (:) is required) - the HTTPS header will then be: Authorization: Basic
YmIwOWMyYjZhOTQ3ODcyMDc2NWM3NTdhOGJjYWRmMWFhMWZiMzE1NTQ1NjZhMjExMThjOWM3NWUyNmMyOTY4Njo=
- With the following given APIKey =
PKI Management
PKI (Public Key Infrastructure) Management is used to generate a private key and signed certificate to be used in generating JSON Web Signatures (JWS) for non-repudiation in our REST endpoints.
To generate your private key and certificate:
- Log on to the Developer Dashboard.
- Navigate to the ‘PKI Management’ screen.
- If this is the first time using this screen the only button available to you will be Generate PKI Key.
- Click this button to generate your Private key and signed certificate.
Once you click the button you will be prompted to download your private key in .key format.
We recommend you store your private key in a secure location such as on a local or cloud based HSM.
After closing the download dialog box you will see your active certificate and there are two actions you can carry out on it:
A | You can download the certificate in .crt format. You will be required to do this to generate JSON Web Signature |
B | You can revoke your active certificate. Note: This will invalidate the active certificate and private key, and you will no longer be able to generate JSON Web Signatures with this key and certificate. You will need to generate a new private key and certificate using the ‘Generate PKI Key’ |
JSON Web Signature
The ‘JSON Web Signature’ (JWS) is used as part of a REST header to validate requests made to create an instant payment. Having this header indicates that you have signed the request with your private key. Any requests to this specific endpoint that does not include the Javascript Object Signing and Encryption (JOSE) header will fail.
Steps Required to Generate a Valid Header
To create a JOSE header you will need to:
- Generate a Private Key and a Certificate (as outlined above).
- Retrieve the certificate serial number and decode it.
- Extract the issuer details from your certificate.
- Use the JWS Signature Generator to generate the JOSE header.
You will then use this header value in any APIs where it is required.
Retrieving Details from the Certificate
In order to generate the JOSE Header you’ll need to extract certain details from your certificate:
- Browse to where you downloaded your certificate (.CRT file) and double-click to view its details.
- Locate the certificate serial number section of the certificate. This is stored as a hexadecimal number and will need to be decoded.
- There are various tools available online to allow you to decode the haxadecimal value, see https://www.rapidtables.com/convert/number/hex-to-decimal.html for example. (The decoded number is the kid value that you will need to generate your Header later).
- Next, locate the subject parameters from the certificate:
Attribute | Value | Description |
OU | Sentenial API | Organization unit, this will always be 'Nuapay API' for certificates signed by Nuapay. |
CN | a2av3py82w | Common name, the originator technical ID |
O | Sentenial | Organization, will always be 'Sentenial' for certificates signed by Sentenial. |
L | London | Locality, will always be 'London' for certificates signed by Sentenial. |
C | GB | Country Name, two letter country code will always be 'GB' for certificates signed by Sentenial. |
At this point you have gathered everything you need from the Certificate. These are the details you need to generate the JOSE Header:
Attribute | Value | Description |
alg | RS256 | Algorithm, always 'RS256' |
kid | 2496611953 | Key ID, use the decoded certificate serial number |
iat | 0 | Issued at, always '0' |
iss | "C=GB, L=London, OU=Sentenial API, O=Sentenial, CN=a2av3py82w" | Issuer, use the certificate subject parameters |
b64 | false | Base64 encoded payload, always 'false' |
crit | ["b64","iat","iss"] | Critical, always ["b64","iat","iss"] |
Use the JWS Signature Generator to generate the JOSE Header.