Authentication Guide

Complete authentication guide for BitMind Enterprise API.

Authentication Methods

Method	Security	Use Case	Setup
OAuth 2.0	⭐⭐⭐	M2M, enterprise integrations	10 min
OAuth + mTLS	⭐⭐⭐⭐⭐	Government, healthcare, financial	30 min
API Key	⭐⭐	Legacy clients	2 min

Method 1: OAuth 2.0 (Recommended)

Quick Start

1. Contact the BitMind team to get your enterprise account set up

2. Visit https://app.bitmind.ai/api/enterprise to create your OAuth client. Use standard (non-mTLS) authentication to follow the rest of the steps on this page with your newly-generated client ID and client secret.

OAuth Flow

# Get token
curl -X POST https://enterprise.bitmind.ai/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_ID" \
  -d "client_secret=YOUR_SECRET"

# Use token
curl https://enterprise.bitmind.ai/image \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: image/jpeg" \
  --data-binary @image.jpg

Python Client

import requests
import time
import os

class BitMindClient:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = "https://enterprise.bitmind.ai"
        self.token = None
        self.token_expires = 0
    
    def get_token(self):
        if self.token and time.time() < self.token_expires - 60:
            return self.token
        
        response = requests.post(
            f"{self.base_url}/v1/oauth/token",
            data={
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret
            }
        )
        response.raise_for_status()
        data = response.json()
        self.token = data["access_token"]
        self.token_expires = time.time() + data["expires_in"]
        return self.token
    
    def process_image(self, image_path):
        with open(image_path, "rb") as f:
            response = requests.post(
                f"{self.base_url}/image",
                headers={
                    "Authorization": f"Bearer {self.get_token()}",
                    "Content-Type": "image/jpeg"
                },
                data=f.read()
            )
        response.raise_for_status()
        return response.json()

# Usage
client = BitMindClient(
    os.getenv("BITMIND_CLIENT_ID"),
    os.getenv("BITMIND_CLIENT_SECRET")
)

result = client.process_image("test.jpg")
print(f"AI: {result['isAI']}, Confidence: {result['confidence']:.2%}")

Token lifetime: 1 hour

Method 2: OAuth + mTLS (High Security)

1. Contact the BitMind team to get your enterprise account set up

2. Visit https://app.bitmind.ai/api/enterprise to create your OAuth client with mTLS encryption. This still will generate client ID and mTLS certificates you will need to download for the first time.

mTLS selection

Quick Start

# Encode certificate
CLIENT_CERT=$(base64 -w 0 client.crt)

# Get token using certificate (NO client_secret needed)
TOKEN=$(curl -s -X POST https://enterprise.bitmind.ai/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-Client-Cert: $CLIENT_CERT" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  | jq -r .access_token)

# Use token with certificate on API calls
curl https://enterprise.bitmind.ai/image \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Client-Cert: $CLIENT_CERT" \
  -H "Content-Type: image/jpeg" \
  --data-binary @test.jpg

Python

import requests
import base64
import time
import os

class BitMindMTLSClient:
    def __init__(self, client_id, cert_path):
        self.client_id = client_id
        self.base_url = "https://enterprise.bitmind.ai"
        self.token = None
        self.token_expires = 0
        
        # Load and encode certificate
        with open(cert_path, "r") as f:
            self.cert_b64 = base64.b64encode(f.read().encode()).decode()
    
    def get_token(self):
        """Get OAuth token using certificate (RFC 8705)"""
        if self.token and time.time() < self.token_expires - 60:
            return self.token
        
        # Certificate replaces client_secret for mTLS clients
        response = requests.post(
            f"{self.base_url}/v1/oauth/token",
            headers={
                "Content-Type": "application/x-www-form-urlencoded",
                "X-Client-Cert": self.cert_b64
            },
            data={
                "grant_type": "client_credentials",
                "client_id": self.client_id
                # NO client_secret - certificate authenticates instead
            }
        )
        response.raise_for_status()
        data = response.json()
        self.token = data["access_token"]
        self.token_expires = time.time() + data["expires_in"]
        return self.token
    
    def process_image(self, image_path):
        """Process image with mTLS"""
        with open(image_path, "rb") as f:
            response = requests.post(
                f"{self.base_url}/image",
                headers={
                    "Authorization": f"Bearer {self.get_token()}",
                    "X-Client-Cert": self.cert_b64,
                    "Content-Type": "image/jpeg"
                },
                data=f.read()
            )
        response.raise_for_status()
        return response.json()

# Usage - only client_id and cert needed (no client_secret!)
client = BitMindMTLSClient(
    os.getenv("BITMIND_CLIENT_ID"),
    "client.crt"
)
result = client.process_image("test.jpg")

Note: Certificates are client-managed. Certificate replaces client_secret for authentication. Contact [email protected] for setup.

Method 3: API Key (Legacy)

1. Contact the BitMind team to get your enterprise account set up

2. Visit https://app.bitmind.ai/api/enterprise to create your API key.

API keys

curl https://enterprise.bitmind.ai/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @image.jpg

Note: OAuth is recommended for new integrations.

Available Endpoints

Endpoint	Method	Auth	Purpose
/v1/oauth/token	POST	client_id/secret	Get token
/health	GET	No	Health check
/status	GET	Yes	Service status
/image	POST	Yes	Single image
/video	POST	Yes	Single video
/batch_image	POST	Yes	Multiple images
/batch_video	POST	Yes	Multiple videos

Response Format

Success

{
  "isAI": true,
  "confidence": 0.8234,
  "processingTime": 0.045
}

• isAI: Boolean (true if confidence >= 0.5)

• confidence: Float (0.0 to 1.0)

• processingTime: Seconds

Error

{
  "detail": "Authorization header required"
}

Best Practices

Security:

• Use environment variables for credentials

• Never commit secrets to git

• Rotate OAuth secrets annually

• Use mTLS for sensitive data

Token Management:

• Cache tokens (1 hour lifetime)

• Auto-refresh before expiry

• Handle 401 errors gracefully

Performance:

• Use batch endpoints for multiple items

• Implement retry logic with exponential backoff

• Monitor response times

Troubleshooting

Error	Cause	Solution
401 Unauthorized	Invalid credentials	Check client_id/secret or API key
401 Token expired	OAuth token > 1 hour	Request new token
403 Forbidden	Permission denied or missing mTLS	Add X-Client-Cert header
429 Too Many Requests	Rate limited	Wait 60s or upgrade tier

Support

• Email: [email protected]

• Response: <4 hours (business hours)

• Documentation: API Endpoints