Authentication
Learn about the authentication scheme required to call Cards Connect APIs
Cards Connect API requires authentication on every request to ensure that the client is identified and the message has not been tampered along the way. The authentication also enforces the permission and access to the appropriate resources and merchant(s) within Cards Connect.
Steps
- Generate two private/public key pairs used for Sandbox and Production environments in JSON Web Keys (JWK) format.
- Share the public keys (in JWK format) with Cards Connect representative. We will use them to generate two API credentials in Sandbox and Production with appropriate permissions and merchant access.
- Store the private keys in your Sandbox and Production servers and use it to sign every request to Cards Connect.
- Before transmitting a request, generate a unique token in the form of a JSON Web Token (JWT), which is the industry standard for representing and validating client claims. The token describes their identity and details of the intended request. This payload is also known as the request metadata.
- Sign the request metadata using the private key to generate a signature in JSON Web Signature (JWS) format and transmit it to Cards Connect in the HTTP request header.
When Cards Connect receives a request, it validates the signature of the metadata using the public key, and compares the transmitted request metadata to the actual request received, looking for discrepancies. If all checks complete successfully, the client is authenticated and the request is processed.
Token Generation Process
The token contains three distinct sections:
| Section | Contents | Usage |
|---|---|---|
| Header | - Client Key ID - Signing Algorithm | Identifies the key and algorithm used to sign the token. |
| Payload | - HTTP Method - API Path - API Query Parameters - Message Checksum (conditional SHA256) - Merchant Id (conditional) - Token Generation Timestamp - Token Expiry Timestamp | Ensures message payload or API parameters are not tampered in transit. Prevents client message repudiation. Identifies the merchant context. |
| Signature | Representation of the token header and payload encrypted with the client’s private key. | Decrypted with the client’s public key. Ensures token authenticity. |
Request Headers
| Header | Description |
|---|---|
| Authorization | The signed token must be prefixed with the text JWS |
Response Authentication
In the future, Cards Connect will digitally sign all responses with the Cards Connect platform's private key. This will enable you to verify that the response originated from us and has not been tampered with.
Updated 3 months ago