Authentication & Security

Weir AI API v1.0.1 provides multiple authentication methods designed for different use cases and security requirements. This guide covers all authentication mechanisms, security best practices, and token management strategies.

Authentication Methods

The Weir AI API supports different authentication methods depending on the API category you’re using:

Basic Authentication

Used for External APIs to generate access tokens with client credentials.

Bearer Token

Used for authenticated requests with access tokens across all API categories.

Session-based

Used for Console and Admin APIs with username/password authentication.

External API Authentication

External APIs use basic authentication to generate access tokens for third-party integrations.

Generate Access Token

curl -X POST 'https://api.weir.ai/auth/token' \
  -H 'Content-Type: application/json' \
  -u 'your_client_id:your_secret_key'

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  },
  "message": "Access token generated successfully",
  "status": "success"
}

Authorization

string

required

Basic authentication header with base64-encoded client credentials. Format: Basic base64(client_id:secret_key)

accessToken

string

required

JWT access token for authenticated API requests. Valid for 1 hour.

expiresIn

integer

Token expiration time in seconds (3600 = 1 hour).

tokenType

string

Token type, always “Bearer” for this API.

Console API Authentication

Console APIs use session-based authentication with username/password login and token refresh capabilities.

Registration

curl -X POST 'https://api.weir.ai/auth/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "fullname": "John Doe",
    "email": "[email protected]",
    "password": "securePassword123",
    "organization": {
      "name": "My Company",
      "type": "Platform",
      "description": "A business platform"
    }
  }'

{
  "data": {
    "otpSession": "otp_session_123456789",
    "message": "Registration successful. Please check your email for OTP verification."
  },
  "status": "success"
}

fullname

string

required

User’s full name for the account.

string

required

Valid email address for the account. Must be unique.

password

string

required

Secure password for the account. Minimum 8 characters with mixed case, numbers, and symbols.

organization

object

required

Organization details for the new account.

Show Organization Properties

organization.name

string

required

Organization name.

organization.type

string

required

Organization type. Options: “Platform”, “Agency”, “Enterprise”.

organization.description

string

Brief description of the organization.

Mobile Registration

curl -X POST 'https://api.weir.ai/auth/m/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "fullname": "John Doe",
    "email": "[email protected]",
    "password": "securePassword123"
  }'

Mobile registration is a simplified version of registration for mobile applications that doesn’t require organization setup.

OTP Validation

curl -X POST 'https://api.weir.ai/auth/validate/registration' \
  -H 'Content-Type: application/json' \
  -d '{
    "otpSession": "otp_session_123456789",
    "otp": "123456"
  }'

otpSession

string

required

OTP session ID received from registration response.

otp

string

required

6-digit OTP code sent to the registered email address.

Resend OTP

curl -X PUT 'https://api.weir.ai/auth/resend/otp/otp_session_123456789' \
  -H 'Content-Type: application/json'

session

string

required

OTP session ID to resend the OTP for.

curl -X POST 'https://api.weir.ai/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "John Doe",
    "password": "securePassword123"
  }'

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_token_123456789",
    "expiresIn": 3600,
    "user": {
      "id": "user_123456789",
      "fullname": "John Doe",
      "email": "[email protected]",
      "role": "Organization_Admin"
    }
  },
  "message": "Login successful",
  "status": "success"
}

username

string

required

User’s full name or email address.

password

string

required

User’s password.

accessToken

string

required

JWT access token for authenticated API requests. Valid for 1 hour.

refreshToken

string

required

Refresh token for obtaining new access tokens. Valid for 30 days.

user

object

User information including ID, name, email, and role.

Show User Properties

user.id

string

Unique user identifier.

user.fullname

string

User’s full name.

user.email

string

User’s email address.

user.role

string

User’s role within the organization.

Refresh Token

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

{
  "data": {
    "accessToken": "new_access_token_here",
    "refreshToken": "new_refresh_token_here",
    "expiresIn": 3600
  },
  "message": "Token refreshed successfully",
  "status": "success"
}

refreshToken

string

required

Valid refresh token obtained from login.

Logout

curl -X POST 'https://api.weir.ai/auth/logout' \
  -H 'Content-Type: application/json' \
  -d '{
    "refreshToken": "refresh_token_123456789"
  }'

refreshToken

string

required

Refresh token to invalidate during logout.

Admin API Authentication

Admin APIs use a special authentication method for administrative access.

Admin Authentication

curl -X POST 'https://api.weir.ai/auth/authenticateAdmin' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "admin_token_here"
  }'

token

string

required

Special admin authentication token provided by system administrators.

Admin authentication tokens are highly sensitive and should only be used by authorized system administrators.

Using Access Tokens

Once you have an access token, include it in the Authorization header for all authenticated requests:

curl -X GET 'https://api.weir.ai/endpoint' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Security Best Practices

Token Management

Secure Storage

Store access tokens securely in environment variables or secure key management systems
Never hardcode tokens in your source code
Use different tokens for different environments (development, staging, production)
Implement token rotation for long-lived applications

Token Refresh

Implement automatic token refresh before expiration
Handle refresh token expiration gracefully
Use exponential backoff for failed refresh attempts
Store refresh tokens securely alongside access tokens

Error Handling

Handle 401 Unauthorized responses by refreshing tokens
Implement proper error logging without exposing sensitive information
Use retry mechanisms for transient authentication failures
Provide clear error messages to users when authentication fails

Request Security

HTTPS Only

Always use HTTPS for all API requests
Never send authentication credentials over unencrypted connections
Validate SSL certificates in production environments
Use certificate pinning for mobile applications

Header Security

Always include the x-source header for Console and Admin APIs
Use appropriate Content-Type headers
Avoid exposing sensitive information in request headers
Implement proper CORS policies for web applications

Input Validation

Validate all input parameters before sending requests
Sanitize user input to prevent injection attacks
Use strong password requirements for user registration
Implement rate limiting on authentication endpoints

Rate Limiting

The Weir AI API implements rate limiting to ensure fair usage and system stability:

Authentication Endpoints

Login: 5 requests per minute per IP
Registration: 3 requests per minute per IP
Token Refresh: 10 requests per minute per user

API Endpoints

External APIs: 100 requests per minute per client
Console APIs: 200 requests per minute per user
Admin APIs: 500 requests per minute per admin

Rate Limit Headers

All API responses include rate limiting information:

X-RateLimit-Limit

string

Maximum number of requests allowed per time window.

X-RateLimit-Remaining

string

Number of requests remaining in the current time window.

X-RateLimit-Reset

string

Unix timestamp when the rate limit window resets.

Handling Rate Limits

Monitor Rate Limit Headers

Check the rate limit headers in API responses to monitor your usage.

Implement Exponential Backoff

When you hit rate limits, implement exponential backoff with jitter.

const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
const jitter = Math.random() * 1000;
await new Promise(resolve => setTimeout(resolve, delay + jitter));

Cache Responses

Cache API responses when possible to reduce the number of requests.

Error Handling

Common Authentication Errors

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": "The provided access token is invalid or has expired"
  },
  "status": "error"
}

Solutions:

Refresh your access token
Re-authenticate if refresh token is also expired
Check token format and ensure it’s properly included in Authorization header

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "Your account does not have permission to access this resource"
  },
  "status": "error"
}

Solutions:

Check your user role and permissions
Contact your organization administrator for access
Verify you’re using the correct API category for your use case

429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": "Rate limit of 100 requests per minute exceeded"
  },
  "status": "error"
}

Solutions:

Implement exponential backoff
Reduce request frequency
Cache responses when possible

Token Lifecycle Management

Token Generation

Generate access tokens through appropriate authentication endpoints based on your API category.

Token Usage

Use access tokens in the Authorization header for all authenticated requests.

Token Refresh

Refresh access tokens before they expire using the refresh token endpoint.

Token Invalidation

Invalidate tokens through logout or when they’re compromised.

Pro Tip: Implement automatic token refresh in your applications to ensure seamless user experience without manual re-authentication.

Security Note: Never expose access tokens in client-side code, URLs, or logs. Always use secure storage mechanisms and proper error handling.

API Playground

Start Here

Quick Start

First Steps

Authentication

Authentication & Security

Authentication & Security

Authentication Methods

Basic Authentication

Bearer Token

Session-based

External API Authentication

Generate Access Token

Console API Authentication

Registration

Mobile Registration

OTP Validation

Resend OTP

Refresh Token

Logout

Admin API Authentication

Admin Authentication

Using Access Tokens

Security Best Practices

Token Management

Request Security

Rate Limiting

Authentication Endpoints

API Endpoints

Rate Limit Headers

Handling Rate Limits

Error Handling

Common Authentication Errors

Token Lifecycle Management

API Playground

Start Here

Quick Start

First Steps

Authentication

​Authentication & Security

​Authentication Methods

Basic Authentication

Bearer Token

Session-based

​External API Authentication

​Generate Access Token

​Console API Authentication

​Registration

​Mobile Registration

​OTP Validation

​Resend OTP

​Login

​Refresh Token

​Logout

​Admin API Authentication

​Admin Authentication

​Using Access Tokens

​Security Best Practices

​Token Management

​Request Security

​Rate Limiting

Authentication Endpoints

API Endpoints

​Rate Limit Headers

​Handling Rate Limits

​Error Handling

​Common Authentication Errors

​Token Lifecycle Management

Authentication & Security

Authentication Methods

External API Authentication

Generate Access Token

Console API Authentication

Registration

Mobile Registration

OTP Validation

Resend OTP

Login

Refresh Token

Logout

Admin API Authentication

Admin Authentication

Using Access Tokens

Security Best Practices

Token Management

Request Security

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Error Handling

Common Authentication Errors

Token Lifecycle Management