Authentication Guide
Learn how to authenticate with B2ALABS API using JWT tokens, API keys, and refresh tokens.
Secure by Default
B2ALABS uses industry-standard authentication mechanisms to protect your data. All API requests require valid authentication credentials.
Authentication Methods
JWT Tokens
Short-lived tokens for user sessions and web applications
USE CASES
- •Web dashboard access
- •User sessions
- •Single-page applications
EXPIRY
1 hour (default)
API Keys
Long-lived keys for programmatic access and automation
USE CASES
- •ServerIcon-to-server communication
- •CI/CD pipelines
- •Automated scripts
EXPIRY
No expiration (revocable)
Refresh Tokens
Long-lived tokens to obtain new access tokens
USE CASES
- •Mobile apps
- •Desktop applications
- •Long-running services
EXPIRY
30 days (default)
JWT Token Authentication
Short-lived tokens for user sessions. Ideal for web applications and SPAs.
1Register a New User
curl -X POST http://localhost:8080/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!",
"name": "John Doe"
}'Response:
{
"data": {
"id": "uuid-here",
"email": "user@example.com",
"name": "John Doe",
"role": "user"
}
}2Login and Get Token
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!"
}'Response:
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2025-10-14T15:00:00Z",
"user": {
"id": "uuid-here",
"email": "user@example.com",
"name": "John Doe",
"role": "user"
}
}
}3Use Token in Requests
curl -X GET http://localhost:8080/api/v1/auth/me \ -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"
Token Structure
JWT tokens have three parts: header.payload.signature
- • Header: Algorithm and token type
- • Payload: User data and claims
- • Signature: Cryptographic signature
API Key Authentication
Long-lived keys for server-to-server communication and automation.
1Create an API Key
First, you need a JWT token to create an API key. Use the login endpoint above.
curl -X POST http://localhost:8080/api/v1/auth/api-keys \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Production API Key",
"permissions": ["ai_gateway", "proxy", "read", "write"],
"expires_at": "2026-10-14T00:00:00Z"
}'Response:
{
"id": "uuid-here",
"name": "Production API Key",
"key": "b2a_xxxxxxxxxxxxxxxxxxxxx",
"key_prefix": "b2a_xxxx",
"permissions": ["ai_gateway", "proxy", "read", "write"],
"expires_at": "2026-10-14T00:00:00Z",
"created_at": "2025-10-14T10:00:00Z"
}Important: The full key is only shown once. Save it securely!
2Use API Key in Requests
curl -X POST http://localhost:8080/api/v1/ai/chat/completions \
-H "Authorization: b2a_xxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'Managing API Keys
List All API Keys
GET /api/v1/auth/api-keys
Revoke an API Key
POST /api/v1/auth/api-keys/:id/revoke
Delete an API Key
DELETE /api/v1/auth/api-keys/:id
Available Permissions
- •
ai_gateway- Access AI Gateway endpoints - •
proxy- Use proxy features - •
read- Read access to resources - •
write- Write access to resources - •
admin- Full administrative access
Refresh Token Flow
Use refresh tokens to obtain new access tokens without re-authentication.
1. Obtain Refresh Token
You receive a refresh token when you login:
{
"token": "eyJ...", // Access token (1 hour)
"refresh_token": "eyJ...", // Refresh token (30 days)
"expires_at": "2025-10-14T15:00:00Z"
}2. Get New Access Token
When your access token expires, use the refresh token:
curl -X POST http://localhost:8080/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "YOUR_REFRESH_TOKEN_HERE"
}'Response:
{
"token": "new_access_token_here",
"refresh_token": "new_refresh_token_here",
"expires_at": "2025-10-14T16:00:00Z"
}Refresh Token Best Practices
- • Store refresh tokens securely (encrypted storage)
- • Refresh access tokens proactively before expiry
- • Rotate refresh tokens on each use (automatic)
- • Revoke refresh tokens on logout
- • Monitor for suspicious refresh patterns
Security Best Practices
Never Commit Secrets
CRITICALNever commit API keys, tokens, or passwords to version control
Rotate Keys Regularly
HIGHRotate API keys every 90 days or immediately if compromised
Use HTTPS Only
CRITICALAlways use HTTPS in production to protect tokens in transit
Implement Rate Limiting
MEDIUMRate limit authentication endpoints to prevent brute force attacks
Scope Permissions
HIGHGrant minimum required permissions (principle of least privilege)
SDK Examples
Use our official SDKs for easier authentication handling
import { B2ALabsClient } from '@b2alabs/sdk';
// Using API Key
const client = new B2ALabsClient({
apiKey: 'b2a_xxxxxxxxxxxxxxxxxxxxx',
baseURL: 'https://api.b2alabs.com'
});
// Make authenticated request
const response = await client.ai.chat.completions({
model: 'gpt-5',
messages: [{ role: 'user', content: 'Hello!' }]
});from b2alabs_sdk import B2ALabsClient
# Using API Key
client = B2ALabsClient(
api_key="b2a_xxxxxxxxxxxxxxxxxxxxx",
base_url="https://api.b2alabs.com"
)
# Make authenticated request
response = await client.ai.chat.completions(
model="gpt-5",
messages=[{"role": "user", "content": "Hello!"}]
)package main
import "github.com/b2alabs/sdk-go"
func main() {
// Using API Key
client := b2alabs.NewClient(
"b2a_xxxxxxxxxxxxxxxxxxxxx",
b2alabs.WithBaseURL("https://api.b2alabs.com"),
)
// Make authenticated request
response, err := client.AI.Chat.Completions(ctx, &b2alabs.ChatRequest{
Model: "gpt-5",
Messages: []b2alabs.Message{
{Role: "user", Content: "Hello!"},
},
})
}What's Next?
Was this page helpful?