Skip to main content

​
Overview

The Soft-Bee API uses JWT (JSON Web Tokens) for authentication. The API provides endpoints for user registration, login, and token management.

​
Authentication Flow

​
1. Register a New User

Create a new user account by sending a POST request to the registration endpoint. 
curl -X POST https://api.soft-bee.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "johndoe",
    "password": "SecurePass123!",
    "confirm_password": "SecurePass123!"
  }'
Response (201 Created): 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "username": "johndoe",
  "is_verified": false,
  "created_at": "2026-03-06T10:30:00",
  "message": "User registered successfully"
}

​
Password Requirements

Passwords must meet the following criteria:
  • Minimum 8 characters
  • At least one uppercase letter (A-Z)
  • At least one lowercase letter (a-z)
  • At least one number (0-9)
  • At least one special character (!@#$%^&*)

​
Username Requirements

  • Minimum 3 characters, maximum 50 characters
  • Only alphanumeric characters and underscores
  • Pattern: ^[a-zA-Z0-9_]+$

​
2. Login

Authenticate with your credentials to receive access and refresh tokens. 
curl -X POST https://api.soft-bee.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "remember_me": false
  }'
Response (200 OK): 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "username": "johndoe",
    "is_verified": true,
    "is_active": true
  }
}

​
Remember Me

The remember_me parameter affects token expiration times:
Token Typeremember_me: falseremember_me: true
Access Token15 minutes (900s)24 hours (86400s)
Refresh Token7 days (604800s)30 days (2592000s)

​
Using JWT Tokens

​
Making Authenticated Requests

Include the access token in the Authorization header using the Bearer scheme: 
curl -X GET https://api.soft-bee.com/api/v1/hives \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Token Structure

JWT tokens issued by Soft-Bee API contain the following claims: Access Token Claims: 
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "username": "johndoe",
  "is_verified": true,
  "type": "access",
  "exp": 1709726400,
  "iat": 1709725500,
  "nbf": 1709725500,
  "iss": "soft-bee-api",
  "aud": "soft-bee-client"
}
Refresh Token Claims: 
{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "type": "refresh",
  "exp": 1712317500,
  "iat": 1709725500,
  "nbf": 1709725500,
  "iss": "soft-bee-api",
  "aud": "soft-bee-client"
}

​
Token Refresh (Coming Soon)

The token refresh endpoint is currently under development. Check back soon for updates.
When your access token expires, you can use the refresh token to obtain a new access token: 
curl -X POST https://api.soft-bee.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

​
Security Best Practices

Never expose your JWT tokens in client-side code, logs, or version control systems.

​
Token Storage

  • Access tokens: Store in memory or secure session storage
  • Refresh tokens: Store in httpOnly cookies or secure storage
  • Never store tokens in localStorage in web applications

​
Token Transmission

  • Always use HTTPS in production
  • Include tokens only in the Authorization header
  • Never send tokens in URL parameters

​
Account Security

  • Failed login attempts are tracked and may result in account lockout
  • Locked accounts cannot authenticate until unlocked by an administrator
  • Account lock error code: ACCOUNT_LOCKED

​
JWT Configuration

The API uses the following JWT configuration:
  • Algorithm: HS256 (HMAC with SHA-256)
  • Default Access Token Expiration: 15 minutes (900 seconds)
  • Default Refresh Token Expiration: 7 days (604800 seconds)
  • Issuer: Configured via JWT_ISSUER environment variable
  • Audience: Configured via JWT_AUDIENCE environment variable

​
Code Examples

​
Python

import requests

# Login
response = requests.post(
    "https://api.soft-bee.com/api/v1/auth/login",
    json={
        "email": "user@example.com",
        "password": "SecurePass123!"
    }
)

data = response.json()
access_token = data["access_token"]

# Make authenticated request
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(
    "https://api.soft-bee.com/api/v1/hives",
    headers=headers
)

​
JavaScript/TypeScript

// Login
const loginResponse = await fetch(
  'https://api.soft-bee.com/api/v1/auth/login',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'user@example.com',
      password: 'SecurePass123!',
    }),
  }
);

const { access_token } = await loginResponse.json();

// Make authenticated request
const response = await fetch(
  'https://api.soft-bee.com/api/v1/hives',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`,
    },
  }
);

​
cURL

# Login and save token
TOKEN=$(curl -X POST https://api.soft-bee.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"SecurePass123!"}' \
  | jq -r '.access_token')

# Use token in subsequent requests
curl -X GET https://api.soft-bee.com/api/v1/hives \
  -H "Authorization: Bearer $TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us