Skip to main content

​
Overview

The Modulus Labs QR API uses HTTP Basic Authentication to secure all API requests. You’ll need your Secret Key, which will be provided by Modulus Labs.
Keep your Secret Key secure! Do not share your authentication credentials in publicly accessible areas such as GitHub, client-side code, or any other public repositories.

​
Your Secret Key

When you sign up, Modulus Labs will provide you with a Secret Key that looks like this: 
sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG
Secret Keys always start with the prefix sk_ to help you identify them.

​
How Basic Authorization Works

HTTP Basic Auth requires a username and password. For the QR API:
  • Username: Your Secret Key
  • Password: Empty string (leave blank)

​
Step-by-Step Process

1

Combine username and password

Combine your Secret Key with a colon (:) and an empty password
sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG:
2

Base64 encode

Apply Base64 encoding to the string from Step 1
c2tfZWFOdjd0NXh5Q3VpQmZHQ3EycTd3dTl1SEVIM21UUTFNcTBjNTNYTzFjNTN2Zkc6
3

Add to header

Add the authorization header with “Basic” followed by the Base64 encoded string
Authorization: Basic c2tfZWFOdjd0NXh5Q3VpQmZHQ3EycTd3dTl1SEVIM21UUTFNcTBjNTNYTzFjNTN2Zkc6

​
Code Examples

Most HTTP clients handle Basic Auth automatically. Here’s how to implement it in different languages: 
const axios = require('axios');

const secretKey = 'sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG';

const response = await axios.post(
  'https://qrph.sbx.moduluslabs.io/v1/pay/qr',
  { Token: encryptedJWE },
  {
    auth: {
      username: secretKey,
      password: ''
    },
    headers: {
      'Content-Type': 'application/json'
    }
  }
);
Notice the colon (:) after the Secret Key in the cURL example. This indicates an empty password.

​
Manual Base64 Encoding

If you need to manually encode the authorization header:

​
Using Command Line

echo -n 'sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG:' | base64

​
Using JavaScript

const secretKey = 'sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG';
const credentials = Buffer.from(`${secretKey}:`).toString('base64');
const authHeader = `Basic ${credentials}`;

​
Security Requirements

HTTPS Only

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication Required

All API requests must include valid authentication credentials or they will fail.

Keep Keys Secure

Never expose your Secret Key in client-side code or public repositories.

Rotate Keys

Regularly rotate your keys and immediately revoke compromised ones.

​
Authentication Errors

If authentication fails, you’ll receive one of these error responses:
Error CodeDescription
10000003Account not found
10000006API Key not found
10000008API Key expired
10000009API Key revoked
10000010API Key suspended
10000011API Key deleted
10000012Unauthorized to perform action
10000013Invalid API Key
10000015Insufficient permissions

​
Example Error Response

{
  "code": "10000013",
  "error": "Invalid API Key",
  "referenceNumber": "338e2710-8268-4afe-8ef9-9765b0b74688"
}
See the Errors page for a complete list of error codes and how to handle them.

​
Testing Your Authentication

Use the Ping endpoint to test your authentication: 
curl https://qrph.sbx.moduluslabs.io/ping \
  -u sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG:
If authentication is successful, you’ll receive: 
Pong!

​
Best Practices

Store your Secret Key in environment variables, never hardcode them in your source code.
const secretKey = process.env.MODULUS_SECRET_KEY;
Regularly rotate your Secret Keys and maintain a grace period where both old and new keys work.
Use separate Secret Keys for sandbox and production environments to prevent accidental charges.
Track authentication failures in your logs to detect potential security issues.
If a Secret Key is compromised, contact Modulus Labs support immediately to revoke it.

​
Next Steps

Encryption Guide

Learn about JWE token encryption for request/response payloads

Create QR Code

Make your first API call to create a Dynamic QR Ph