FG API

Appearance

Authentication API Reference ​

This reference covers authentication endpoints and token management in the FG API platform.

Authentication Overview ​

FG API uses JWT (JSON Web Token) based authentication with refresh tokens for secure access management.

Token Types ​

Access Token ​

  • Purpose: Authenticate API requests

  • Lifetime: 1 hour

  • Usage: Include in Authorization header for API calls

  • Format: Bearer YOUR_ACCESS_TOKEN

Refresh Token ​

  • Purpose: Obtain new access tokens

  • Lifetime: 7 days

  • Usage: Exchange for new access tokens when current one expires

  • Format: Bearer YOUR_REFRESH_TOKEN

Authentication Endpoints ​

User Login ​

Authenticate a user and receive access tokens.

Endpoint: POST /app/login

Headers:

en
Content-Type: application/json

Request Body:

json
{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

json
{
  "user": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "username": "john_doe",
    "email": "user@example.com",
    "status": "approved"
  }
}

Error Responses:

401 Unauthorized (Invalid credentials):

json
{
  "error": "Invalid email or password"
}

403 Forbidden (Account pending approval):

json
{
  "error": "account pending approval"
}

429 Too Many Requests (Rate limited):

json
{
  "error": "Too many authentication attempts, please try again later",
  "retryAfter": "15 minutes"
}

User Registration ​

Register a new user account.

Endpoint: POST /app/register

Headers:

Content-Type: application/json

Request Body:

json
{
  "username": "john_doe",
  "email": "user@example.com",
  "password": "secure-password",
  "approvalCode": "APPROVAL_CODE"
}

Response:

json
{
  "message": "User registered successfully. Account pending approval."
}

Error Responses:

400 Bad Request (Validation error):

json
{
  "error": "validation failed",
  "details": "Email is required"
}

409 Conflict (User already exists):

json
{
  "error": "duplicate entry",
  "details": "A user with this email already exists"
}

403 Forbidden (Invalid approval code):

json
{
  "error": "Invalid approval code"
}

Refresh Access Token ​

Get a new access token using a refresh token.

Endpoint: POST /app/refresh

Headers:

Authorization: Bearer YOUR_REFRESH_TOKEN
Content-Type: application/json

Response:

json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Responses:

401 Unauthorized (Invalid refresh token):

json
{
  "error": "Invalid refresh token"
}

401 Unauthorized (Refresh token expired):

json
{
  "error": "Refresh token expired"
}

Using Authentication ​

Making Authenticated Requests ​

Include the access token in the Authorization header:

javascript
fetch('https://your-api.com/api/endpoints', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  }
})

Automatic Token Refresh ​

The client automatically handles token refresh:

  1. Request with expired token → Returns 401
  2. Client detects 401 → Automatically calls refresh endpoint
  3. New access token received → Updates stored token
  4. Original request retried → With new access token
  5. Request succeeds → User stays logged in

Token Storage ​

Tokens are stored securely in the browser's localStorage:

javascript
// Storing tokens after login
localStorage.setItem('user', JSON.stringify({
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  refreshToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  username: 'john_doe',
  email: 'user@example.com',
  status: 'approved'
}));

// Retrieving tokens for API calls
const userData = JSON.parse(localStorage.getItem('user'));
const accessToken = userData.accessToken;

User Status ​

Pending Approval ​

  • Status: "pending"

  • Access: Limited to authentication endpoints only

  • Actions: Cannot create or manage APIs

  • Next Step: Wait for administrator approval

Approved Users ​

  • Status: "approved"

  • Access: Full access to all platform features

  • Actions: Can create, edit, and delete APIs

  • Features: Access to analytics, monitoring, and management tools

Security Features ​

Rate Limiting ​

Authentication Endpoints ​

  • Limit: 5 requests per 15 minutes

  • Scope: Per IP address + User Agent

  • Purpose: Prevent brute force attacks

API Endpoints ​

  • Limit: 100 requests per 15 minutes

  • Scope: Per IP address (fallback) or per authenticated user

  • Purpose: Prevent API abuse

User-Specific Limits ​

  • Limit: 200 requests per 15 minutes

  • Scope: Per authenticated user

  • Purpose: Fair usage for authenticated users

Token Security ​

Access Token Security ​

  • Lifetime: 1 hour (short-lived for security)

  • Storage: Browser localStorage

  • Usage: API request authentication

  • Refresh: Automatic via refresh token

Refresh Token Security ​

  • Lifetime: 7 days (longer-lived for convenience)

  • Storage: Browser localStorage

  • Usage: Obtain new access tokens

  • Rotation: New refresh token on each refresh

CORS Protection ​

  • Origin Validation: Only configured domains allowed

  • Credentials: Proper handling of cookies and auth headers

  • Preflight: Cached preflight requests for performance

Error Handling ​

Authentication Errors ​

Token Missing ​

json
{
  "error": "token missing"
}

Token Invalid ​

json
{
  "error": "token invalid"
}

Token Expired ​

json
{
  "tokenExpired": true,
  "error": "token expired"
}

Account Pending Approval ​

json
{
  "error": "account pending approval"
}

Rate Limiting Errors ​

Too Many Requests ​

json
{
  "error": "Too many requests, please try again later",
  "retryAfter": "15 minutes"
}

Authentication Rate Limit ​

json
{
  "error": "Too many authentication attempts, please try again later",
  "retryAfter": "15 minutes"
}

Best Practices ​

Password Security ​

  • Use strong, unique passwords

  • Don't share credentials

  • Change passwords regularly

  • Use password managers

Token Management ​

  • Don't manually edit tokens in browser storage

  • Log out when using shared computers

  • Report suspicious activity immediately

  • Monitor your API usage regularly

API Security ​

  • Always use HTTPS for API requests

  • Don't expose tokens in client-side code

  • Implement proper error handling

  • Monitor for unusual activity

Examples ​

Complete Authentication Flow ​

1. User Registration ​

javascript
const registerResponse = await fetch('/app/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'john_doe',
    email: 'john@example.com',
    password: 'secure-password',
    approvalCode: 'APPROVAL_CODE'
  })
});

const registerData = await registerResponse.json();
console.log(registerData.message); // "User registered successfully. Account pending approval."

2. User Login ​

javascript
const loginResponse = await fetch('/app/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'john@example.com',
    password: 'secure-password'
  })
});

const loginData = await loginResponse.json();
const { accessToken, refreshToken } = loginData.user;

// Store tokens
localStorage.setItem('user', JSON.stringify(loginData.user));

3. Making Authenticated API Calls ​

javascript
const userData = JSON.parse(localStorage.getItem('user'));
const accessToken = userData.accessToken;

const apiResponse = await fetch('/api/endpoints', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const endpoints = await apiResponse.json();

4. Automatic Token Refresh ​

javascript
// This happens automatically in the background
const refreshResponse = await fetch('/app/refresh', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${refreshToken}`,
    'Content-Type': 'application/json'
  }
});

const refreshData = await refreshResponse.json();
const newAccessToken = refreshData.accessToken;

// Update stored token
const updatedUser = {
  ...userData,
  accessToken: newAccessToken
};
localStorage.setItem('user', JSON.stringify(updatedUser));

cURL Examples ​

Login ​

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

Register ​

bash
curl -X POST https://your-api.com/app/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "user@example.com",
    "password": "secure-password",
    "approvalCode": "APPROVAL_CODE"
  }'

Refresh Token ​

bash
curl -X POST https://your-api.com/app/refresh \
  -H "Authorization: Bearer YOUR_REFRESH_TOKEN" \
  -H "Content-Type: application/json"

Authenticated API Call ​

bash
curl -X GET https://your-api.com/api/endpoints \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Troubleshooting ​

Common Issues ​

"Account pending approval" ​

  • Your account is waiting for administrator approval

  • Contact your administrator for approval

  • You'll receive access once approved

"Token expired" ​

  • Your access token has expired

  • The system will automatically refresh it

  • If refresh fails, you'll need to log in again

"Too many requests" ​

  • You've hit the rate limit

  • Wait 15 minutes before trying again

  • Consider reducing request frequency

"Invalid credentials" ​

  • Check your email and password

  • Ensure caps lock is off

  • Try resetting your password if needed

Getting Help ​

  • Check the Authentication Guide

  • Contact support through the platform

  • Review error messages for specific details

  • Check your account status in the dashboard