Copy page

API Reference

Authentication How-To

Overview

Primebrick supports three authentication methods for API access. Choose the one that matches your use case:

• User Access Token — for end users logging in with username/password.
• OAuth2 Client Credentials — for server-to-server, machine-to-machine calls.
• API Key — for third-party integrations and simple scripting.

Each method is covered below with copy-paste code examples in cURL, JavaScript, Python, and PHP.

Method 1: User Access Token (User Way)

Best for: end users logging in with a username and password (e.g. the admin frontend).

Flow:

1. POST /api/v1/auth/login with username + password
2. Receive a JWT access token in the response body and a refresh token in an HTTP-only cookie
3. Send the access token as a Bearer token in the Authorization header on subsequent requests

cURL

Login request:

Code
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin@primebrick.dev",
    "password": "your-password"
  }'

Response:

Code
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Authenticated request:

Code
curl http://localhost:3001/api/v1/customers \
  -H "Authorization: Bearer eyJhbGciOi..."

JavaScript (fetch)

Code
// 1. Login
const loginRes = await fetch("http://localhost:3001/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include", // receive the refresh-token cookie
  body: JSON.stringify({
    username: "admin@primebrick.dev",
    password: "your-password",
  }),
});

const { access_token } = await loginRes.json();

// 2. Authenticated request
const dataRes = await fetch("http://localhost:3001/api/v1/customers", {
  headers: { Authorization: `Bearer ${access_token}` },
  credentials: "include",
});

const customers = await dataRes.json();

Python (requests)

Code
import requests

base = "http://localhost:3001"

# 1. Login
login = requests.post(
    f"{base}/api/v1/auth/login",
    json={"username": "admin@primebrick.dev", "password": "your-password"},
)
login.raise_for_status()
access_token = login.json()["access_token"]

# session keeps the refresh-token cookie for later refresh calls
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {access_token}"})

# 2. Authenticated request
customers = session.get(f"{base}/api/v1/customers").json()

PHP (curl)

Code
<?php
// 1. Login
$ch = curl_init("http://localhost:3001/api/v1/auth/login");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER         => true, // keep cookies
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "username" => "admin@primebrick.dev",
        "password" => "your-password",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);

// parse access_token from the JSON body
preg_match('/\{.*\}/s', $response, $matches);
$body = json_decode($matches[0], true);
$accessToken = $body["access_token"];

// 2. Authenticated request
$ch = curl_init("http://localhost:3001/api/v1/customers");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer {$accessToken}"],
]);
$customers = json_decode(curl_exec($ch), true);
curl_close($ch);

Note: Access tokens are short-lived. When the token expires, call POST /api/v1/auth/refresh (the refresh token is sent automatically via the HTTP-only cookie) to obtain a new access token without re-entering credentials.

Method 2: OAuth2 Client Credentials (Client Way)

Best for: server-to-server communication, scheduled jobs, and microservice-to-microservice calls where no user is involved.

Flow:

1. POST /api/v1/auth/token with client_id + client_secret + grant_type=client_credentials
2. Receive an access token in the response body
3. Send the access token as a Bearer token in the Authorization header

cURL

Token request:

Code
curl -X POST http://localhost:3000/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Response:

Code
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Authenticated request:

Code
curl http://localhost:3001/api/v1/customers \
  -H "Authorization: Bearer eyJhbGciOi..."

JavaScript (fetch)

Code
// 1. Request a token
const tokenRes = await fetch("http://localhost:3000/api/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
  }),
});

const { access_token } = await tokenRes.json();

// 2. Authenticated request
const dataRes = await fetch("http://localhost:3001/api/v1/customers", {
  headers: { Authorization: `Bearer ${access_token}` },
});

const customers = await dataRes.json();

Python (requests)

Code
import requests

base = "http://localhost:3000"

# 1. Request a token
token = requests.post(
    f"{base}/api/v1/auth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
    },
)
token.raise_for_status()
access_token = token.json()["access_token"]

# 2. Authenticated request
session = requests.Session()
session.headers.update({"Authorization": f"Bearer {access_token}"})
customers = session.get("http://localhost:3001/api/v1/customers").json()

PHP (curl)

Code
<?php
// 1. Request a token
$ch = curl_init("http://localhost:3000/api/v1/auth/token");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        "grant_type"    => "client_credentials",
        "client_id"     => "YOUR_CLIENT_ID",
        "client_secret" => "YOUR_CLIENT_SECRET",
    ]),
]);
$token = json_decode(curl_exec($ch), true);
curl_close($ch);

$accessToken = $token["access_token"];

// 2. Authenticated request
$ch = curl_init("http://localhost:3001/api/v1/customers");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer {$accessToken}"],
]);
$customers = json_decode(curl_exec($ch), true);
curl_close($ch);

Note: Client credentials are obtained from the Primebrick admin panel or directly from Casdoor. Treat them like passwords — store them in a secrets manager, never in source control.

Method 3: API Key (Third-Party Way)

Best for: third-party integrations, simple scripts, and any scenario where token exchange logic is overkill.

Flow:

1. Obtain an API key from the Primebrick admin panel
2. Send the key as an X-API-Key header on every request

No token exchange, no refresh logic, no cookie handling.

cURL

Code
curl http://localhost:3001/api/v1/customers \
  -H "X-API-Key: <YOUR_API_KEY>"

JavaScript (fetch)

Code
const res = await fetch("http://localhost:3001/api/v1/customers", {
  headers: { "X-API-Key": "<YOUR_API_KEY>" },
});

const customers = await res.json();

Python (requests)

Code
import requests

customers = requests.get(
    "http://localhost:3001/api/v1/customers",
    headers={"X-API-Key": "<YOUR_API_KEY>"},
).json()

PHP (curl)

Code
<?php
$ch = curl_init("http://localhost:3001/api/v1/customers");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-API-Key: <YOUR_API_KEY>"],
]);
$customers = json_decode(curl_exec($ch), true);
curl_close($ch);

Note: API keys are long-lived but revocable from the admin panel. They can also be scoped to specific permissions, limiting what a third party can do if a key is leaked.

Comparison Table

Method	Use Case	Token Type	Expiry	Scopes
User Token	End user login	JWT	Short-lived (refresh)	User permissions
Client Credentials	Server-to-server	JWT	Short-lived	Client permissions
API Key	Third-party integrations	Static key	No expiry (revocable)	Scoped permissions

API Explorer

The API Explorer on this site uses API keys for simplicity. To try the API:

1. Get an API key from your Primebrick admin panel.
2. Enter it in the config panel at the top of the API Explorer page.
3. The key is sent as an X-API-Key header on all requests.

Note: User tokens (username/password → JWT) and OAuth2 client credentials are fully supported by the Primebrick platform, but they are not exposed in the API Explorer REPL yet. The explorer's auth UI supports bearer tokens and API keys. For full OAuth2 flows, use Casdoor directly or your own client.