Skip to content

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

Login
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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
Login
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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
Login
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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();
    }
}

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.