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.

Info

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

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

Login to Get JWT

• Method: POST
• Endpoint: /api/v1/auth/login
• Description: Authenticate a user and obtain a JSON Web Token (JWT) to access secured API endpoints.

Parameters

Name	Type	Required	Description
password	string	Yes	The 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"
}

---

Check Authentication Status

• Method: GET
• Endpoint: /api/v1/auth/status
• Description: Validate the authentication status of the current session by checking the provided token.

Parameters

Name	Type	Required	Description
Authorization	string	Yes	Bearer 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"
}

Password Encryption Helpers

Below you will find several code snippets to help you encrypt your Gunbot password for authentication requests.

JavaScript - Browser Environment

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 Environment

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 on your system.
• This script uses no salt and ensures binary output before Base64 encoding.

#!/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 the -A option to openssl enc to avoid line wrapping if necessary.

---

Python (Using OpenSSL via Subprocess)

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}")

Note: Ensure openssl is installed on your system for the Bash and Python examples to function correctly.