Authentication

Overview

The BR-ACC API uses JWT (JSON Web Token) authentication with HTTP-only cookies for secure session management. Authentication is required for most API endpoints.

Authentication Flow

Register a new user account with an email and password (requires invite code if configured)
Login with credentials to receive a JWT access token
Include the token in requests via Bearer Authorization header or cookie
Logout to invalidate the session cookie

Registration

Create a new user account.

Endpoint

POST /api/v1/auth/register

Rate Limit: 10 requests per minute

Request Body

string

required

User’s email address. Maximum 254 characters.

password

string

required

User’s password. Must be between 8 and 128 characters.

invite_code

string

default:""

Invitation code (required if INVITE_CODE environment variable is configured on the server).

Example Request

curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd",
    "invite_code": "your-invite-code"
  }'

Response

string

Unique user identifier (UUID).

string

User’s email address.

created_at

string

ISO 8601 timestamp of when the user was created.

Success Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "created_at": "2026-03-05T14:30:00Z"
}

Error Responses

403 Forbidden - Invalid invite code:

{
  "detail": "Invalid invite code"
}

409 Conflict - Email already registered:

{
  "detail": "Email already registered"
}

Authenticate with credentials to receive a JWT access token.

Endpoint

POST /api/v1/auth/login

Rate Limit: 10 requests per minute

Request Body

The login endpoint uses OAuth2 password flow format (application/x-www-form-urlencoded):

username

string

required

User’s email address (OAuth2 convention uses “username” field).

password

string

required

User’s password.

Example Request

curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=SecureP@ssw0rd"

Response

access_token

string

JWT access token for authenticating subsequent requests.

token_type

string

default:"bearer"

Token type (always “bearer”).

Success Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

On successful login, the API sets an HTTP-only cookie named bracc_session (configurable via AUTH_COOKIE_NAME) with the following attributes:

Max-Age: 1440 minutes (24 hours) by default (configurable via JWT_EXPIRE_MINUTES)
HttpOnly: true (prevents JavaScript access)
Secure: true in production (requires HTTPS)
SameSite: lax (configurable: lax, strict, none)
Path: /

Error Response

401 Unauthorized - Invalid credentials:

{
  "detail": "Invalid credentials"
}

Using the Access Token

Include the JWT token in subsequent requests using one of these methods:

Method 1: Authorization Header (Recommended)

curl -X GET "http://localhost:8000/api/v1/auth/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

If your client supports cookies, the session cookie is automatically included:

curl -X GET "http://localhost:8000/api/v1/auth/me" \
  --cookie "bracc_session=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Get Current User

Retrieve information about the currently authenticated user.

Endpoint

GET /api/v1/auth/me

Authentication: Required

Example Request

curl -X GET "http://localhost:8000/api/v1/auth/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

string

User’s unique identifier.

string

User’s email address.

created_at

string

ISO 8601 timestamp of when the user was created.

Success Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "created_at": "2026-03-05T14:30:00Z"
}

Logout

Invalidate the current session by deleting the session cookie.

Endpoint

POST /api/v1/auth/logout

Authentication: Not required (but clears cookie if present)

Example Request

curl -X POST "http://localhost:8000/api/v1/auth/logout" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (204 No Content) No response body. The bracc_session cookie is deleted.

JWT Token Structure

The JWT token contains the following payload:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "exp": 1743868800
}

sub

string

Subject (user ID).

exp

integer

Expiration time (Unix timestamp).

Token Configuration

JWT tokens are configured with:

Algorithm: HS256 (HMAC with SHA-256)
Expiration: 1440 minutes (24 hours) by default
Secret Key: Configured via JWT_SECRET_KEY environment variable (must be >= 32 characters in production)

Security Considerations

Password Requirements

Minimum length: 8 characters
Maximum length: 128 characters
Passwords are hashed using bcrypt before storage

JWT Secret Key

In production environments, you must set a strong JWT secret key:

export JWT_SECRET_KEY="your-secure-random-secret-key-at-least-32-characters-long"

Using the default JWT secret key (change-me-in-production) will cause the API to fail startup in production mode.

Rate Limiting for Authentication

Authentication endpoints are strictly rate-limited to 10 requests per minute to prevent brute-force attacks.

Invite Codes

If your deployment requires controlled registration, set the INVITE_CODE environment variable:

export INVITE_CODE="your-secure-invite-code"

When configured, all registration requests must include a matching invite_code in the request body.

Environment Variables

JWT_SECRET_KEY

string

default:"change-me-in-production"

Secret key for signing JWT tokens. Must be >= 32 characters in production.

JWT_ALGORITHM

string

default:"HS256"

Algorithm for JWT signing (only HS256 is supported).

JWT_EXPIRE_MINUTES

integer

default:"1440"

JWT token expiration time in minutes (default: 24 hours).

INVITE_CODE

string

default:""

Required invite code for registration (empty = no invite code required).

Name of the session cookie.

Whether to set the Secure flag on session cookies (automatically true in production).

SameSite attribute for session cookies (lax, strict, or none).

Next Steps

Search Entities

Search for entities using your access token

Entity Details

Retrieve detailed entity information

Overview

Public Endpoints

Graph Operations

Authentication

Overview

Authentication Flow

Registration

Endpoint

Request Body

Example Request

Response

Error Responses

Endpoint

Request Body

Example Request

Response

Error Response

Using the Access Token

Method 1: Authorization Header (Recommended)

Get Current User

Endpoint

Example Request

Response

Logout

Endpoint

Example Request

JWT Token Structure

Token Configuration

Security Considerations

Password Requirements

JWT Secret Key

Rate Limiting for Authentication

Invite Codes

Environment Variables

Next Steps

Search Entities

Entity Details

Build docs developers (and LLMs) love

Overview

Public Endpoints

Graph Operations

​Overview

​Authentication Flow

​Registration

​Endpoint

​Request Body

​Example Request

​Response

​Error Responses

​Login

​Endpoint

​Request Body

​Example Request

​Response

​Session Cookie

​Error Response

​Using the Access Token

​Method 1: Authorization Header (Recommended)

​Method 2: Session Cookie

​Get Current User

​Endpoint

​Example Request

​Response

​Logout

​Endpoint

​Example Request

​JWT Token Structure

​Token Configuration

​Security Considerations

​Password Requirements

​JWT Secret Key

​Rate Limiting for Authentication

​Invite Codes

​Environment Variables

​Next Steps

Search Entities

Entity Details

Build docs developers (and LLMs) love

Overview

Authentication Flow

Registration

Endpoint

Request Body

Example Request

Response

Error Responses

Login

Endpoint

Request Body

Example Request

Response

Session Cookie

Error Response

Using the Access Token

Method 1: Authorization Header (Recommended)

Method 2: Session Cookie

Get Current User

Endpoint

Example Request

Response

Logout

Endpoint

Example Request

JWT Token Structure

Token Configuration

Security Considerations

Password Requirements

JWT Secret Key

Rate Limiting for Authentication

Invite Codes

Environment Variables

Next Steps