API Authentication Guide

This guide provides a comprehensive overview of how to authenticate with the Breden API securely. Following these steps will ensure your API calls are authorized and your data remains protected.

keyStep 1: Generating Your Authentication Token and Key

Before making any authenticated requests, you must first obtain a plain token and a plain key from our dedicated token generation API endpoint. This initial call does not require encryption.

API Endpoint: /user/v1/generateKeyToken
Method: POST (or GET if it's a simple token generation without user data)

Upon a successful call, the API will return a response containing your token and key.

{
  "token": "22f632f1d31cc2dcff47ab4fd2720c63",
  "key": "54c3ac7333fd510b2512a475d4d2bef1"
}

Store these values temporarily, as they will be used in the next step for encryption.

lockStep 2: Encrypting Your Credentials (AES-256-CBC)

To ensure secure communication, the token and key obtained in Step 1 must be encrypted using the AES-256-CBC method. You will use a pre-shared secret key and an Initialization Vector (IV) for this process. The token and key are encrypted using AES-256-CBC with a shared encryption key and a IV.

Encryption Details:

Method: AES-256-CBC
Key: Received from Dashboard (32 bytes)
IV: Received from Dashboard (16 bytes)

Below are code examples demonstrating how to perform this encryption in various programming languages.

<?php
function encryptAES($plaintext, $key, $iv) {
  $cipher = "AES-256-CBC";
  $options = OPENSSL_RAW_DATA;

  $encrypted = openssl_encrypt($plaintext, $cipher, $key, $options, $iv);
  return base64_encode($encrypted);
}

$key = "54c3ac7333fd510b2512a475d4d2bef1";
$iv = "1234567812345678";
$plaintext = "22f632f1d31cc2dcff47ab4fd2720c63";

$encrypted_token = encryptAES($plaintext, $key, $iv);
echo "Encrypted Token: " . $encrypted_token;
?>

const crypto = require('crypto');

function encryptAES(plaintext, key, iv) {
  const cipher = crypto.createCipheriv('aes-256-cbc', Buffer.from(key, 'utf8'), Buffer.from(iv, 'utf8'));
  let encrypted = cipher.update(plaintext, 'utf8', 'base64');
  encrypted += cipher.final('base64');
  return encrypted;
}

const key = "54c3ac7333fd510b2512a475d4d2bef1";
const iv = "1234567812345678";
const plaintext = "22f632f1d31cc2dcff47ab4fd2720c63";

const encryptedToken = encryptAES(plaintext, key, iv);
console.log("Encrypted Token:", encryptedToken);

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

public class AesEncryption
{
  public static string EncryptAES(string plainText, string key, string iv)
  {
      using (Aes aesAlg = Aes.Create())
      {
          aesAlg.KeySize = 256;
          aesAlg.BlockSize = 128;
          aesAlg.Mode = CipherMode.CBC;
          aesAlg.Padding = PaddingMode.PKCS7;
          aesAlg.Key = Encoding.UTF8.GetBytes(key);
          aesAlg.IV = Encoding.UTF8.GetBytes(iv);

          ICryptoTransform encryptor = aesAlg.CreateEncryptor(aesAlg.Key, aesAlg.IV);

          using (MemoryStream msEncrypt = new MemoryStream())
          {
              using (CryptoStream csEncrypt = new CryptoStream(msEncrypt, encryptor, CryptoStreamMode.Write))
              {
                  using (StreamWriter swEncrypt = new StreamWriter(csEncrypt))
                  {
                      swEncrypt.Write(plainText);
                  }
                  return Convert.ToBase64String(msEncrypt.ToArray());
              }
          }
      }
  }

  public static void Main(string[] args)
  {
      string key = "54c3ac7333fd510b2512a475d4d2bef1";
      string iv = "1234567812345678";
      string plaintext = "22f632f1d31cc2dcff47ab4fd2720c63";

      string encryptedToken = EncryptAES(plaintext, key, iv);
      Console.WriteLine("Encrypted Token: " + encryptedToken);
  }
}

      import javax.crypto.Cipher;
      import javax.crypto.spec.IvParameterSpec;
      import javax.crypto.spec.SecretKeySpec;
      import java.nio.charset.StandardCharsets;
      import java.util.Base64;

      public class AesEncryption {

          public static String encryptAES(String plainText, String key, String iv) throws Exception {
              Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
              SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "AES");
              IvParameterSpec ivParameterSpec = new IvParameterSpec(iv.getBytes(StandardCharsets.UTF_8));

              cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivParameterSpec);

              byte[] encryptedBytes = cipher.doFinal(plainText.getBytes(StandardCharsets.UTF_8));
              return Base64.getEncoder().encodeToString(encryptedBytes);
          }

          public static void main(String[] args) throws Exception {
              String key = "54c3ac7333fd510b2512a475d4d2bef1";
              String iv = "1234567812345678";
              String plaintext = "22f632f1d31cc2dcff47ab4fd2720c63";

              String encryptedToken = encryptAES(plaintext, key, iv);
              System.out.println("Encrypted Token: " + encryptedToken);
          }
      }

list-altStep 3: Constructing Your Request Headers

Once your token and key are encrypted, you will include them in the headers of your subsequent API requests. Additionally, you will include a Crop-Code that is provided to you separately (e.g., via email).

Required Headers:

X-Breden-Token: Your encrypted token.
X-Breden-Key: Your encrypted key.
Crop-Code: The unique code provided to you.

Example HTTP Request Headers:

X-Breden-Token: <your_encrypted_token>
X-Breden-Key: <your_encrypted_key>
X-Breden-CropCode: YOUR_CROP_CODE
Content-Type: application/json

Ensure these headers are present in all requests requiring authentication.

API Environments

Breden provides separate environments for development/testing and live production usage.

flask

Staging Environment

Base URL: https://staging.breden.in/api
Use this environment for all your development and testing activities. It mirrors the live environment but does not affect production data.

rocket

Live Environment

Base URL: https://api.breden.in/api
This is the production environment. All your live applications and user interactions should target this endpoint.

Best Practices and Troubleshooting

To ensure a smooth and secure integration, consider the following best practices:

Secure Key Management:

Never hardcode sensitive keys directly in your client-side code.
Use environment variables or a secure vault service to store your master encryption keys and Crop-Code.
Rotate your Crop-Code periodically if possible.

Handle Token Expiration:

Tokens may have an expiration time. Implement logic to detect expired tokens and automatically request new ones using the /token/generate endpoint.
Monitor API responses for specific error codes related to authentication failures.

If you encounter any issues during the authentication process, please refer to our FAQ or contact our support team with details of the problem, including request/response headers and any error messages received.

API Key	Label	Last Used