Skip to main content

Authentication

Authentication is required to access protected endpoints in the Gunbot API. This section covers the /api/v1/auth/login endpoint for obtaining a JSON Web Token (JWT) and the /api/v1/auth/status endpoint to validate authentication.

Gunbot uses password encryption to ensure secure communication during authentication. Sample code snippets for encrypting passwords in different programming environments are provided.

/api/v1/auth/login​

  • Method: POST
  • Description: Authenticate a user and obtain a JSON Web Token (JWT) to access secured API endpoints.

Parameters​

NameTypeRequiredDescription
passwordstringYesThe user's encrypted password. See encryption helpers below.

Examples​

cURL​

curl -X POST https://your-gunbot-instance.com:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -d '{"password": "your_encrypted_password"}'

JavaScript (fetch API)​

fetch('https://your-gunbot-instance.com:3000/api/v1/auth/login', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer YOUR_BEARER_TOKEN' 
  },
  body: JSON.stringify({ password: 'your_encrypted_password' }),
})
  .then(response => response.json())
  .then(data => console.log(data.token));

Python (requests library)​

import requests

url = 'https://your-gunbot-instance.com:3000/api/v1/auth/login'
data = {'password': 'your_encrypted_password'}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer YOUR_BEARER_TOKEN'
}
response = requests.post(url, json=data, headers=headers)
print(response.json()['token'])

Response​

Success (200)​

{
  "status": "success",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE4MTEwNjM4NTIsImlhdCI6MTczMzMXAwSnRyVi5JWmEwd0Vrc3lULnVCOVYxWXRObjAwRVB6NXlwTWo4UjRPblJoOFl1WGhxIn0.h1QiXh3EGl_LCqh0cgBTBle2ALgjSNhZPN9uwpvug6c"
}

/api/v1/auth/status​

  • Method: GET
  • Description: Validate the authentication status of the current session by checking the provided token.

Parameters​

NameTypeRequiredDescription
AuthorizationstringYesBearer token. Include in the Authorization header as Bearer <token>.

Examples​

cURL​

curl -X GET https://your-gunbot-instance.com:3000/api/v1/auth/status \
  -H "Authorization: Bearer your_token"

JavaScript (fetch API)​

fetch('https://your-gunbot-instance.com:3000/api/v1/auth/status', {
  headers: { 'Authorization': 'Bearer your_token' }
})
  .then(response => response.json())
  .then(data => console.log(data.status));

Python (requests library)​

import requests

url = 'https://your-gunbot-instance.com:3000/api/v1/auth/status'
headers = {'Authorization': 'Bearer your_token'}
response = requests.get(url, headers=headers)
print(response.json()['status'])

Response​

Success (200)​

{
  "code": 200,
  "isDemo": false,
  "isRegistered": true,
  "isTwoFA": false,
  "metamask": false,
  "status": "success",
  "message": "Authenticated"
}

Encryption helpers​

Below you'll find several snippets to help you encrypt your Gunbot password for auth requests.

JavaScript - Browser​

async function encryptPassword(password, key) {
  const encoder = new TextEncoder();
  const data = encoder.encode(password);
  const encodedKey = encoder.encode(key).slice(0, 16);
  const iv = encodedKey;

  const cryptoKey = await window.crypto.subtle.importKey(
    'raw',
    encodedKey,
    { name: 'AES-CBC' },
    false,
    ['encrypt']
  );

  const encryptedBuffer = await window.crypto.subtle.encrypt(
    { name: 'AES-CBC', iv },
    cryptoKey,
    data
  );

  const encryptedBytes = new Uint8Array(encryptedBuffer);
  const encryptedBase64 = btoa(String.fromCharCode(...encryptedBytes));
  return `ENC:${encryptedBase64}`;
}

// Example usage in a browser environment:
// encryptPassword('your_password', 'value for config.bot.gunthy_wallet')

JavaScript - Node.js​

const crypto = require('crypto');

function encryptPassword(password, key) {
  const encryptionKey = Buffer.from(key).slice(0, 16);
  const iv = encryptionKey;

  const cipher = crypto.createCipheriv('aes-128-cbc', encryptionKey, iv);
  const encrypted = Buffer.concat([cipher.update(password, 'utf8'), cipher.final()]);
  
  // Convert to Base64 and add prefix
  return 'ENC:' + encrypted.toString('base64');
}

// Example usage:
// console.log(encryptPassword('your_password', 'value for config.bot.gunthy_wallet'));

Bash (Using OpenSSL)​

Requirements:

  • openssl must be installed.
  • No salt used, and ensure binary output before base64.
#!/usr/bin/env bash

PASSWORD="your_password"
KEY="value for config.bot.gunthy_wallet"

# Truncate key to 16 bytes
KEY_TRUNC=$(echo -n "$KEY" | head -c 16)

# Convert key and IV to hex
KEY_HEX=$(echo -n "$KEY_TRUNC" | xxd -p)
IV_HEX=$KEY_HEX

# Encrypt using openssl (no salt)
# -nosalt to prevent adding salt bytes
ENCRYPTED_BASE64=$(echo -n "$PASSWORD" | openssl enc -aes-128-cbc -K "$KEY_HEX" -iv "$IV_HEX" -nosalt -base64)

# Add prefix
echo "ENC:${ENCRYPTED_BASE64}"

Note: If you find a difference in output compared to the browser result, ensure no extra newline or whitespace is affecting the base64 output. You can add -A to openssl enc to avoid line wrapping if necessary.

Make sure openssl is installed on your system.

Python (Using OpenSSL from subprocess, no extra crypto libs)​

import subprocess

password = 'your_password'
key = 'value for config.bot.gunthy_wallet'

# Truncate key to 16 bytes
key_trunc = key[:16]

# Convert key to hex
key_hex = key_trunc.encode('utf-8').hex()
iv_hex = key_hex  # same as key

# Run openssl command
res = subprocess.run([
    'openssl', 'enc', '-aes-128-cbc',
    '-K', key_hex,
    '-iv', iv_hex,
    '-nosalt',
    '-base64'
], input=password.encode('utf-8'), stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)

encrypted_base64 = res.stdout.decode().strip()

print(f"ENC:{encrypted_base64}")

Make sure openssl is installed on your system.