Documentation API ReferenceAuthentication

Authentication

API Authentication

Learn how to authenticate with the BotLaunch API using JWT tokens. Secure your requests and manage access to your resources.

JWT Tokens

Secure stateless authentication using JSON Web Tokens.

Token Expiry

Access tokens expire in 1 hour, refresh tokens in 7 days.

Auto Refresh

Use refresh tokens to obtain new access tokens seamlessly.

Authentication Flow

Follow these steps to authenticate and make secure API requests.

Login

Obtain tokens with credentials

Store Tokens

Securely store both tokens

Make Requests

Include token in headers

Refresh

Get new token when expired

Authentication Endpoints

POST/api/auth/login

Authenticate a user and receive access and refresh tokens.

Request Body

Field	Type	Required	Description
email	string		User's email address
password	string		User's password

Example Request

curl -X POST "https://api.botlaunch.io/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-secure-password"
  }'

bash

Example Response

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "role": "CLIENT_OWNER"
    }
  },
  "message": "Login successful"
}

json

POST/api/auth/register

Create a new user account and organization.

Request Body

Field	Type	Required	Description
email	string		Valid email address
password	string		Min 8 chars, 1 uppercase, 1 number
name	string		User's full name
organizationName	string	Optional	Organization name

Example Request

curl -X POST "https://api.botlaunch.io/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "SecureP@ssw0rd!",
    "name": "John Doe",
    "organizationName": "My Company"
  }'

bash

POST/api/auth/refresh

Exchange a refresh token for a new access token.

Example Request

curl -X POST "https://api.botlaunch.io/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token"
  }'

bash

Token Rotation

Each refresh request returns a new refresh token. Store and use the latest refresh token for subsequent requests.

POST/api/auth/logout

Invalidate the current session and revoke tokens.

Example Request

curl -X POST "https://api.botlaunch.io/api/auth/logout" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

bash

Using Access Tokens

Include your access token in the Authorization header for all API requests.

// Include the access token in all API requests
const response = await fetch("https://api.botlaunch.io/api/bots", {
  headers: {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "x-organization-id": "org_xyz789",
    "Content-Type": "application/json"
  }
});

javascript

Required Headers

AuthorizationBearer token

x-organization-idOrganization ID

Content-Typeapplication/json

Security Best Practices

Store tokens securely (never in localStorage for web)
Use HTTPS for all API requests
Implement token refresh before expiry
Revoke tokens on logout or security events

Authentication Errors

Common authentication errors and how to handle them.

Status	Error	Description	Solution
401	Unauthorized	Missing or invalid token	Check Authorization header
401	Token Expired	Access token has expired	Use refresh token to get new access token
403	Forbidden	Insufficient permissions	Check user role and organization access
429	Too Many Requests	Login rate limit exceeded	Wait and retry after cooldown
400	Invalid Credentials	Wrong email or password	Verify credentials and try again

API Overview Bots API