Authentication

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

Combine username and password

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

sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG:

Base64 encode

Apply Base64 encoding to the string from Step 1

c2tfZWFOdjd0NXh5Q3VpQmZHQ3EycTd3dTl1SEVIM21UUTFNcTBjNTNYTzFjNTN2Zkc6

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'
    }
  }
);

import requests

secret_key = 'sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG'

response = requests.post(
    'https://qrph.sbx.moduluslabs.io/v1/pay/qr',
    json={'Token': encrypted_jwe},
    auth=(secret_key, ''),
    headers={'Content-Type': 'application/json'}
)

<?php

$secretKey = 'sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG';

$ch = curl_init('https://qrph.sbx.moduluslabs.io/v1/pay/qr');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['Token' => $encryptedJWE]));
curl_setopt($ch, CURLOPT_USERPWD, $secretKey . ':');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

import java.net.http.*;
import java.util.Base64;

String secretKey = "sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG";
String auth = secretKey + ":";
String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://qrph.sbx.moduluslabs.io/v1/pay/qr"))
    .header("Authorization", "Basic " + encodedAuth)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

curl https://qrph.sbx.moduluslabs.io/v1/pay/qr \
  -u sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG: \
  -H "Content-Type: application/json" \
  -d '{"Token": "eyJhbGciOiJBMjU2S1ciL..."}'

package main

import (
	"bytes"
	"fmt"
	"net/http"
)

func main() {
	secretKey := "sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG"

	req, _ := http.NewRequest("POST",
		"https://qrph.sbx.moduluslabs.io/v1/pay/qr",
		bytes.NewBufferString(`{"Token": "eyJhbGciOiJBMjU2S1ciL..."}`))
	req.SetBasicAuth(secretKey, "")
	req.Header.Set("Content-Type", "application/json")

	resp, err := (&http.Client{}).Do(req)
	if err != nil {
		fmt.Printf("Request failed: %v\n", err)
		return
	}
	defer resp.Body.Close()

	fmt.Printf("Status: %d\n", resp.StatusCode)
}

using System.Net.Http.Headers;
using System.Text;

var secretKey = "sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG";

using var client = new HttpClient();
var authBytes = Encoding.ASCII.GetBytes($"{secretKey}:");
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", Convert.ToBase64String(authBytes));

var content = new StringContent(
    "{\"Token\": \"eyJhbGciOiJBMjU2S1ciL...\"}",
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://qrph.sbx.moduluslabs.io/v1/pay/qr",
    content
);

var body = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Response: {body}");

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

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("sk_eaNv7t5xyCuiBfGCq2q7wu9uHEH3mTQ1Mq0c53XO1c53vfG:"))

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 Code	Description
`10000003`	Account not found
`10000006`	API Key not found
`10000008`	API Key expired
`10000009`	API Key revoked
`10000010`	API Key suspended
`10000011`	API Key deleted
`10000012`	Unauthorized to perform action
`10000013`	Invalid API Key
`10000015`	Insufficient 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

Use Environment Variables

Store your Secret Key in environment variables, never hardcode them in your source code.

const secretKey = process.env.MODULUS_SECRET_KEY;

Implement Key Rotation

Regularly rotate your Secret Keys and maintain a grace period where both old and new keys work.

Use Different Keys for Environments

Use separate Secret Keys for sandbox and production environments to prevent accidental charges.

Monitor Authentication Failures

Track authentication failures in your logs to detect potential security issues.

Revoke Compromised Keys Immediately

If a Secret Key is compromised, contact Modulus Labs support immediately to revoke it.

QR API

Onboarding API

Terminal Gateway

Transaction Reporting API

Ecom API

Shared Resources

Overview

Your Secret Key

How Basic Authorization Works

Step-by-Step Process

Code Examples

Manual Base64 Encoding

Using Command Line

Using JavaScript

Security Requirements

HTTPS Only

Authentication Required

Keep Keys Secure

Rotate Keys

Authentication Errors

Example Error Response

Testing Your Authentication

Best Practices

Next Steps

Encryption Guide

Create QR Code

​Overview

​Your Secret Key

​How Basic Authorization Works

​Step-by-Step Process

​Code Examples

​Manual Base64 Encoding

​Using Command Line

​Using JavaScript

​Security Requirements

HTTPS Only

Authentication Required

Keep Keys Secure

Rotate Keys

​Authentication Errors

​Example Error Response

​Testing Your Authentication

​Best Practices

​Next Steps

Encryption Guide

Create QR Code

Overview

Your Secret Key

How Basic Authorization Works

Step-by-Step Process

Code Examples

Manual Base64 Encoding

Using Command Line

Using JavaScript

Security Requirements

Authentication Errors

Example Error Response

Testing Your Authentication

Best Practices

Next Steps