Authentication Guide
Complete authentication guide for BitMind Enterprise API.
Authentication Methods
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
Contact the BitMind team to get your enterprise account set up
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.
# 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.jpgPython 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)
Contact the BitMind team to get your enterprise account set up
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.
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.jpgPython
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)
Contact the BitMind team to get your enterprise account set up
Visit https://app.bitmind.ai/api/enterprise to create your API key.
curl https://enterprise.bitmind.ai/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: image/jpeg" \
--data-binary @image.jpgNote: OAuth is recommended for new integrations.
Available Endpoints
/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
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
Last updated