Authentication

Areal API support multiple authentication mechanisms:

• JWT over cookies (recommended)
• JWT over Bearer
• ApiKey over headers (on-demand)
• MFA over Authenticator App (Google Authenticator, PingID, Authy, etc.)

Authentication Flow

Below is a high-level sequence diagram illustrating the main phases of the authentication lifecycle:

sequenceDiagram
    participant User as 👤 User
    participant Frontend as 🖥️ Areal Dashboard
    participant API as 🖥️ Areal API

    %% Phase 1: Login
    rect rgb(220,255,220)
    User->>Frontend: Enter credentials
    Frontend->>API: POST /login (credentials)
    API-->>Frontend: Set secure cookies (access & refresh tokens)
    Frontend-->>User: Login success
    end

    %% Phase 2: Authenticated Request
    rect rgb(200,220,255)
    User->>Frontend: Perform action
    Frontend->>API: Authenticated request (cookies sent automatically)
    API-->>Frontend: Protected resource/data
    end

    %% Phase 3: Token Refresh
    rect rgb(255,240,200)
    Frontend->>API: Token expired, use refresh token (cookie)
    API-->>Frontend: Issue new access token (cookie)
    end

    %% Phase 4: Logout
    rect rgb(255,220,220)
    User->>Frontend: Click logout
    Frontend->>API: POST /logout
    API-->>Frontend: Clear cookies
    Frontend-->>User: Logged out
    end

Example Usage

Python

Login

import requests

BASE_URL = 'http://dev-api.v2.areal.ai/api/v2'

# 0. Login - details in Authentication section
login_response = requests.post(f'{BASE_URL}/accounts/login/', {
    'username': 'test@areal.ai',
    'password': 'test123',
})
client = requests.Session()
client.cookies.update(
    {
        'access_token': login_response.cookies['access_token'],
        'refresh_token': login_response.cookies['refresh_token'],
    }
)
# this client is now authenticated for the duration of access_token
# after that you can refresh it using the /accounts/refresh endpoint

C#

Login

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
using System.Text.Json;
using System.Net;

var baseUrl = "http://dev-api.v2.areal.ai/api/v2";

// 0. Login - details in Authentication section
var loginData = new
{
    username = "test@areal.ai",
    password = "test123"
};

var handler = new HttpClientHandler
{
    UseCookies = true,
    CookieContainer = new CookieContainer()
};
var client = new HttpClient(handler);

var loginContent = new StringContent(
    JsonSerializer.Serialize(loginData),
    Encoding.UTF8,
    "application/json"
);

var loginResponse = await client.PostAsync($"{baseUrl}/accounts/login/", loginContent);
loginResponse.EnsureSuccessStatusCode();

// Cookies (access_token and refresh_token) are automatically stored in handler.CookieContainer
// This client is now authenticated for the duration of access_token
// after that you can refresh it using the /accounts/refresh endpoint

Java

Login

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.CookieManager;
import java.net.CookieHandler;
import java.net.HttpCookie;
import java.nio.charset.StandardCharsets;

public class Login {
    public static void main(String[] args) throws Exception {
        String baseUrl = "http://dev-api.v2.areal.ai/api/v2";

        // 0. Login - details in Authentication section
        CookieManager cookieManager = new CookieManager();
        CookieHandler.setDefault(cookieManager);

        URL url = new URL(baseUrl + "/accounts/login/");
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setDoOutput(true);

        String loginData = "{\"username\":\"test@areal.ai\",\"password\":\"test123\"}";

        try (OutputStream os = connection.getOutputStream()) {
            byte[] input = loginData.getBytes(StandardCharsets.UTF_8);
            os.write(input, 0, input.length);
        }

        int responseCode = connection.getResponseCode();
        if (responseCode == HttpURLConnection.HTTP_OK) {
            // Cookies are automatically stored in the CookieManager
            // this client is now authenticated for the duration of access_token
            // after that you can refresh it using the /accounts/refresh endpoint
        }

        connection.disconnect();
    }
}

API Key

Use an API key for scripts and service-to-service calls (no login cookies). Send the same key on every request in one of these headers:

• Authorization: Bearer <api_key> (recommended)
• key: <api_key>

JavaScript

API Key

const BASE_URL = 'https://dev-api.v2.areal.ai/api/v2';
const API_KEY = process.env.AREAL_API_KEY;

if (!API_KEY) {
  throw new Error('Set AREAL_API_KEY in the environment');
}

// Preferred: Authorization: Bearer <api_key>
const meResponse = await fetch(`${BASE_URL}/accounts/me/`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});

if (!meResponse.ok) {
  throw new Error(`Auth failed: ${meResponse.status} ${await meResponse.text()}`);
}

const me = await meResponse.json();
console.log(me);

// Alternative: custom `key` header (ArealAPIKeyHeader)
const altResponse = await fetch(`${BASE_URL}/accounts/me/`, {
  headers: {
    key: API_KEY,
  },
});

console.log(await altResponse.json());

Security Highlights

• Secure Login: Credentials are never stored or transmitted in plain text.
• Token-Based Authentication: Access and refresh tokens are used to manage sessions securely.
• Cookie Usage: Secure, HTTP-only cookies are used to store tokens, protecting them from XSS attacks.
• Session Refresh: Seamless token refresh ensures uninterrupted user experience.
• Logout: Users can securely terminate their sessions at any time.
• Best-Practice Security: All authentication flows use encryption, secure cookie flags, and protection against common web vulnerabilities.

---

For technical integration details see Accounts.