API Key Authenticated Endpoints

These endpoints can be authenticated using a combination of your API Key and a signature.

First, make sure to register your API key in the Register an API key for the current user. The endpoint expects 3 inputs:

Name: a name for your API key. Can be anything.
Public Key: the public key of a RSA key pair generated by you. The public key should be in PKIX DER format, pem encoded. E.g.:

Signature: this signature is obtained by using the private key generated with the public key to sign the payload obtained by applying the SHA256 hashing algorithm to the same name you sent as input. This is meant simply to help you verify if your public key was successfully accepted and it's ready to verify your API calls.

To access the API endpoints using API Key authentication, you must pass the following headers in your http request:

X-API-Key: {Your API Key hHere}
X-API-Timestamp: {Timestamp in UNIX milliseconds format}
X-API-Signature: {An unique base64 encoded signature you must generate for each of your requests}

The signature you have to send is obtained by the following procedure:

Concatenate as text: {Timestamp}{Request method}{Endpoint path with query parameters}{Body JSON, if present}
Apply the SHA256 hashing algorithm.
Sign the payload with your private key using RSASSA-PKCS1-V1_5-SIGN from RSA PKCS #1 v1.5
Encode the result into a base64 string.

A full example is provided below:

Creating the key pair

privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
  log.Fatal(err)
}
publicKey := &privateKey.PublicKey

privateKeyBytes := x509.MarshalPKCS1PrivateKey(privateKey)
privateKeyBlock := &pem.Block{
  Type:  "RSA PRIVATE KEY",
  Bytes: privateKeyBytes,
}
privateKeyEncoded := pem.EncodeToMemory(privateKeyBlock)

publicKeyBytes, err := x509.MarshalPKIXPublicKey(publicKey)
if err != nil {
  log.Fatal(err)
}
publicKeyBlock := &pem.Block{
  Type:  "PUBLIC KEY",
  Bytes: publicKeyBytes,
}
publicKeyEncoded := pem.EncodeToMemory(publicKeyBlock)

log.Println(string(privateKeyEncoded))

log.Println(string(publicKeyEncoded))

from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives import serialization

private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
    backend=default_backend()
)

private_key_pem = private_key.private_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PrivateFormat.TraditionalOpenSSL,
    encryption_algorithm=serialization.NoEncryption()
)

public_key = private_key.public_key()

public_key_pem = public_key.public_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PublicFormat.SubjectPublicKeyInfo
)

print(private_key_pem.decode('utf-8'))
print(public_key_pem.decode('utf-8'))

const crypto = require('crypto');

const { publicKey, privateKey } = crypto.generateKeyPairSync('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs1',
    format: 'pem'
  }
});

console.log('Private Key:', privateKey);
console.log('Public Key:', publicKey);

require 'openssl'

private_key = OpenSSL::PKey::RSA.new(2048)

public_key = private_key.public_key

private_key_pem = private_key.to_pem
public_key_pem = public_key.to_pem

puts "Private Key:\n#{private_key_pem}"
puts "Public Key:\n#{public_key_pem}"

using System;
using System.Security.Cryptography;
using System.Text;

class Program
{
    static void Main()
    {
        using (var rsa = new RSACryptoServiceProvider(2048))
        {
            rsa.PersistKeyInCsp = false;

            string privateKey = Convert.ToBase64String(rsa.ExportCspBlob(true));
            string publicKey = Convert.ToBase64String(rsa.ExportCspBlob(false));

            Console.WriteLine("Private Key:\n" + privateKey);
            Console.WriteLine("Public Key:\n" + publicKey);
        }
    }
}

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.util.Base64;

public class RSAKeyPairExample{
    public static void main (String[] args) throws Exception {
        KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA");
        kpg.initialize(2048); KeyPair kp = kpg.generateKeyPair();

        System.out.println ("-----BEGIN PRIVATE KEY-----");
        System.out.println (Base64.getMimeEncoder().encodeToString( kp.getPrivate().getEncoded()));
        System.out.println ("-----END PRIVATE KEY-----\n");
        System.out.println ("-----BEGIN PUBLIC KEY-----");
        System.out.println (Base64.getMimeEncoder().encodeToString( kp.getPublic().getEncoded()));
        System.out.println ("-----END PUBLIC KEY-----");

    }
}

openssl genrsa -out keypair.pem 2048
openssl rsa -in keypair.pem -pubout -out publickey.pem

In this example, the keys generated were:

Signing the API Key register request

privateKeyFile, err := os.ReadFile("privatekey.pem")
if err != nil {
  log.Fatal(err)
}

privateKeyBlock, _ := pem.Decode(privateKeyFile)
if privateKeyBlock == nil {
  log.Fatal("error decoding private key")
}

privateKey, err := x509.ParsePKCS1PrivateKey(privateKeyBlock.Bytes)
if err != nil {
  log.Fatal(err)
}

const keyName = "My API Key"

hasher := sha256.New()
hasher.Write([]byte(keyName))
hash := hasher.Sum(nil)

signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, hash)
if err != nil {
  log.Fatal(err)
}

base64Signature := base64.StdEncoding.EncodeToString(signature)

log.Println("Signature:", base64Signature) // MMZaJGPtXq571wHdUe/Z/mifFbnnjKJUEgChY1nYREAETNY5vbDo5JM/LOLxQtE5CYtPhcm7w214Vlblh2hoKDLjLALfeyFPo0DpeIyV3EWnr/qQ4F1jYJiP44ke9AKxURctVFqJtLm12ABJ25fPDeTXrfKnZTn+SY3JctRZDD5KHx4ZgM96jgJFU2kLJvrsof/6mdCri2IiHTdwpEuxdnHMnwc2j3yjoJ2IwCsr7n7L+H44S0GYK/dOL/n0cZAmxmFw1m0vB03CdrAoGtbaweTaBtg6psrjrvzkqJOXq9AgWJVoMCx4Hoe8o3txf5l7NZYIrLtQu/CieXSJoMwrDQ==

# Library used: pycryptodome
from Crypto.PublicKey import RSA
from Crypto.Signature.pkcs1_15 import PKCS115_SigScheme
from Crypto.Hash import SHA256
import base64

privKeyTxt = open("privateKey.pem", "r").read()

keyPair = RSA.importKey(privKeyTxt)
pubKey = keyPair.publickey() # Just showing how to get the public key as well

msg = b'My API Key'
hash = SHA256.new(msg)
signer = PKCS115_SigScheme(keyPair)
signature = signer.sign(hash)
print("Signature:", base64.b64encode(signature)) # MMZaJGPtXq571wHdUe/Z/mifFbnnjKJUEgChY1nYREAETNY5vbDo5JM/LOLxQtE5CYtPhcm7w214Vlblh2hoKDLjLALfeyFPo0DpeIyV3EWnr/qQ4F1jYJiP44ke9AKxURctVFqJtLm12ABJ25fPDeTXrfKnZTn+SY3JctRZDD5KHx4ZgM96jgJFU2kLJvrsof/6mdCri2IiHTdwpEuxdnHMnwc2j3yjoJ2IwCsr7n7L+H44S0GYK/dOL/n0cZAmxmFw1m0vB03CdrAoGtbaweTaBtg6psrjrvzkqJOXq9AgWJVoMCx4Hoe8o3txf5l7NZYIrLtQu/CieXSJoMwrDQ==

const fs = require('fs');
const crypto = require('crypto');

const privateKey = fs.readFileSync('privateKey.pem', 'utf8');

const message = 'YOUR NAME APIKEY HERE';

const sign = crypto.createSign('RSA-SHA256');
sign.update(message);

console.log(sign.sign(privateKey, 'base64'));

require 'openssl'
require 'base64'

private_key = OpenSSL::PKey::RSA.new(File.read("privateKey.pem"))

key_name = "My API Key"

digest = OpenSSL::Digest::SHA256.new
hash = digest.digest(key_name)

signature = private_key.sign(digest, key_name)

base64_signature = Base64.encode64(signature).strip

puts "Signature: #{base64_signature}"

using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;

class Program
{
    static void Main()
    {
        var privateKeyText = File.ReadAllText("privateKey.pem");
        var privateKey = RSA.Create();
        privateKey.ImportFromPem(privateKeyText.ToCharArray());

        const string keyName = "My API Key";

        var hash = SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(keyName));

        var signature = privateKey.SignHash(hash, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);

        var base64Signature = Convert.ToBase64String(signature);

        Console.WriteLine("Signature: " + base64Signature);
    }
}

import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import java.security.MessageDigest;

public class RSASignatureExample {
    public static void main(String[] args) throws Exception {
        String privateKeyPEM = new String(Files.readAllBytes(Paths.get("privateKey.pem")));

        privateKeyPEM = privateKeyPEM.replace("-----BEGIN PRIVATE KEY-----", "")
                                     .replace("-----END PRIVATE KEY-----", "")
                                     .replaceAll("\\s+", "");

        byte[] privateKeyBytes = Base64.getDecoder().decode(privateKeyPEM);

        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(privateKeyBytes);
        KeyFactory keyFactory = KeyFactory.getInstance("RSA");
        PrivateKey privateKey = keyFactory.generatePrivate(keySpec);

        String keyName = "My API Key";

        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(keyName.getBytes("UTF-8"));

        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);
        signature.update(hash);
        byte[] signedHash = signature.sign();

        String base64Signature = Base64.getEncoder().encodeToString(signedHash);

        System.out.println("Signature: " + base64Signature);
    }
}

Sending the request and registering the API Key

POST /business/api-keys
Accept: application/json
Authorization: Bearer {JWT Token Here}

{
"name":"My API Key",
"publicKey":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp2sCMqZe2cePRooomyX+\nS3/yfGS3g7TG3eur2gtAtD6PVKaLlv5Sk/d0zyJXrWaBIrVoU2rlKLGqKhsql1vT\nB6IcPsIwN4qK5guMC2Mi2+j7dCoGSY1wU4sDTO6L7fsBKp7tvKw1H11h6Xoan05j\nfyPGvg4TKhOd9LZHwPCfZCU20L33s0ryQj4T6v/eGtoT4HCfrMlPLIj7zq4TIHgq\nHUhnYYsRLJO179JblPqErZzu3iFshjDoIdparO3WWO+Z7bq+9JqdLpgJywZuvAUp\nZd8yNgQcZ0mNnV/GXniMz/U8NbQbFDeF6eLmCnALT2l20Et2wOAjgY2GAwNyzSsc\nhQIDAQAB\n-----END PUBLIC KEY-----",
"signature": "MMZaJGPtXq571wHdUe/Z/mifFbnnjKJUEgChY1nYREAETNY5vbDo5JM/LOLxQtE5CYtPhcm7w214Vlblh2hoKDLjLALfeyFPo0DpeIyV3EWnr/qQ4F1jYJiP44ke9AKxURctVFqJtLm12ABJ25fPDeTXrfKnZTn+SY3JctRZDD5KHx4ZgM96jgJFU2kLJvrsof/6mdCri2IiHTdwpEuxdnHMnwc2j3yjoJ2IwCsr7n7L+H44S0GYK/dOL/n0cZAmxmFw1m0vB03CdrAoGtbaweTaBtg6psrjrvzkqJOXq9AgWJVoMCx4Hoe8o3txf5l7NZYIrLtQu/CieXSJoMwrDQ=="
}

-> Response
{
  "apiKey": "ab3915e6-4886-4fef-b3a6-5855962ffbb8"
}

Calling the Create Pay-Out endpoint

timestamp := time.Now().UnixMilli()
requestMethod := http.MethodPost
endpointPath := "/v1/business/pay-out"

bodyData, _ := json.Marshal(struct {
  PixKey string `json:"pixKey"`
  Amount        int64  `json:"amount"`
}{
  PixKey: "pixKeyHere",
  Amount:        20000,
})

content := fmt.Sprintf("%s%s%s%s", strconv.FormatInt(timestamp, 10), requestMethod, endpointPath, string(bodyData))

hasher := sha256.New()
hasher.Write([]byte(content))
hash := hasher.Sum(nil)

signature, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, hash)
if err != nil {
  log.Fatal(err)
}

base64Signature := base64.StdEncoding.EncodeToString(signature)

req, _ := http.NewRequest(requestMethod, apiUrl+endpointPath, bytes.NewReader(bodyData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "ab3915e6-4886-4fef-b3a6-5855962ffbb8")
req.Header.Set("X-API-Timestamp", strconv.FormatInt(timestamp, 10))
req.Header.Set("X-API-Signature", base64Signature)
res, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer res.Body.Close()

if res.StatusCode != http.StatusCreated {
  log.Fatal("error creating buy request")
}

import time
import json
import hashlib
import base64
import requests
from Crypto.PublicKey import RSA
from Crypto.Signature.pkcs1_15 import PKCS115_SigScheme
from Crypto.Hash import SHA256

timestamp = int(time.time() * 1000)
request_method = "POST"
endpoint_path = "/v1/business/pay-out"
pix_key = "pixKeyHere"
amount = 20000

body_data = json.dumps({
    "pixKey": pix_key,
    "amount": amount
})

content = f"{timestamp}{request_method}{endpoint_path}{body_data}"

hash_obj = SHA256.new(content.encode())

private_key = RSA.import_key(open("privateKey.pem").read())
signer = PKCS115_SigScheme(private_key)
signature = signer.sign(hash_obj)
base64_signature = base64.b64encode(signature).decode()

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "ab3915e6-4886-4fef-b3a6-5855962ffbb8",
    "X-API-Timestamp": str(timestamp),
    "X-API-Signature": base64_signature
}

response = requests.post(f"https://api.brla.digital:5567{endpoint_path}", headers=headers, data=body_data)

if response.status_code != 201:
    raise Exception("Error creating pay-out request")

print("Pay-out request created successfully")

const crypto = require('crypto');
const fs = require('fs');
const axios = require('axios');

const timestamp = Date.now();
const requestMethod = 'POST';
const endpointPath = '/v1/business/pay-out';
const bodyData = JSON.stringify({
    pixKey: 'pixKeyHere',
    amount: 20000
});

const content = `${timestamp}${requestMethod}${endpointPath}${bodyData}`;

const privateKey = crypto.createPrivateKey(fs.readFileSync('privateKey.pem', 'utf8'));
const sign = crypto.createSign('RSA-SHA256');

sign.update(content);
const signature = sign.sign(privateKey, 'base64');

// 'YOUR API KEY',
const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': "YOUR APIKEY HERE",
    'X-API-Timestamp': timestamp.toString(),
    'X-API-Signature': signature
};

axios.post('https://api.brla.digital:4567/v1/business/pay-out', bodyData, { headers })
    .then(response => {
        if (response.status !== 201) {
            throw new Error('Error creating pay-out request');
        }
        console.log('Pay-out request created successfully');
    })
    .catch(error => {
        console.error(error);
    });

require 'net/http'
require 'json'
require 'openssl'
require 'base64'

timestamp = (Time.now.to_f * 1000).to_i
request_method = "POST"
endpoint_path = "/v1/business/pay-out"
body_data = {
  pixKey: "pixKeyHere",
  amount: 20000
}.to_json

content = "#{timestamp}#{request_method}#{endpoint_path}#{body_data}"

digest = OpenSSL::Digest::SHA256.new
hash = digest.digest(content)

private_key = OpenSSL::PKey::RSA.new(File.read("privateKey.pem"))
signature = private_key.sign(digest, content)
base64_signature = Base64.strict_encode64(signature)

uri = URI("https://api.brla.digital:5567#{endpoint_path}")
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-API-Key'] = 'ab3915e6-4886-4fef-b3a6-5855962ffbb8'
req['X-API-Timestamp'] = timestamp.to_s
req['X-API-Signature'] = base64_signature
req.body = body_data

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

if res.code.to_i != 201
  raise "Error creating pay-out request"
end

puts "Pay-out request created successfully"

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        long timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
        string requestMethod = "POST";
        string endpointPath = "/v1/business/pay-out";
        string bodyData = "{\"pixKey\": \"pixKeyHere\", \"amount\": 20000}";

        string content = $"{timestamp}{requestMethod}{endpointPath}{bodyData}";

        using (var sha256 = SHA256.Create())
        {
            byte[] hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(content));

            var privateKeyText = System.IO.File.ReadAllText("privateKey.pem");
            var privateKey = RSA.Create();
            privateKey.ImportFromPem(privateKeyText.ToCharArray());

            byte[] signature = privateKey.SignHash(hash, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
            string base64Signature = Convert.ToBase64String(signature);

            using (var client = new HttpClient())
            {
                var request = new HttpRequestMessage(HttpMethod.Post, $"https://api.brla.digital:5567{endpointPath}");
                request.Content = new StringContent(bodyData, Encoding.UTF8, "application/json");
                request.Headers.Add("X-API-Key", "ab3915e6-4886-4fef-b3a6-5855962ffbb8");
                request.Headers.Add("X-API-Timestamp", timestamp.ToString());
                request.Headers.Add("X-API-Signature", base64Signature);

                var response = await client.SendAsync(request);

                if (response.StatusCode != System.Net.HttpStatusCode.Created)
                {
                    throw new Exception("Error creating pay-out request");
                }

                Console.WriteLine("Pay-out request created successfully");
            }
        }
    }
}

import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.MessageDigest;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;

public class PayoutRequest {
    public static void main(String[] args) throws Exception {
        long timestamp = System.currentTimeMillis();
        String requestMethod = "POST";
        String endpointPath = "/v1/business/pay-out";
        String bodyData = "{\"pixKey\": \"pixKeyHere\", \"amount\": 20000}";

        String content = timestamp + requestMethod + endpointPath + bodyData;

        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(content.getBytes(StandardCharsets.UTF_8));

        String privateKeyPEM = new String(Files.readAllBytes(Paths.get("privateKey.pem")))
                .replace("-----BEGIN PRIVATE KEY-----", "")
                .replace("-----END PRIVATE KEY-----", "")
                .replaceAll("\\s+", "");
        byte[] privateKeyBytes = Base64.getDecoder().decode(privateKeyPEM);
        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(privateKeyBytes);
        PrivateKey privateKey = java.security.KeyFactory.getInstance("RSA").generatePrivate(keySpec);

        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);
        signature.update(hash);
        byte[] signedHash = signature.sign();
        String base64Signature = Base64.getEncoder().encodeToString(signedHash);

        URL url = new URL("https://api.brla.digital:5567" + endpointPath);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("X-API-Key", "ab3915e6-4886-4fef-b3a6-5855962ffbb8");
        conn.setRequestProperty("X-API-Timestamp", String.valueOf(timestamp));
        conn.setRequestProperty("X-API-Signature", base64Signature);
        conn.setDoOutput(true);

        conn.getOutputStream().write(bodyData.getBytes(StandardCharsets.UTF_8));

        int responseCode = conn.getResponseCode();
        if (responseCode != HttpURLConnection.HTTP_CREATED) {
            throw new RuntimeException("Error creating pay-out request");
        }

        System.out.println("Pay-out request created successfully");
    }
}