Skip to content
HomeStar Docs

Authentication

The API supports two authentication methods: API keys for programmatic access and JWT tokens for browser-based applications.

Authentication Methods

Section titled “Authentication Methods”

API Key Authentication

Section titled “API Key Authentication”

API keys are the recommended method for server-to-server integrations.

X-API-Key: idx_a1b2c3d4e5f6g7h8i9j0

API keys can be created by administrators through the admin panel or API endpoint. See the Managing API Keys guide for instructions.

JWT Token Authentication (OIDC)

Section titled “JWT Token Authentication (OIDC)”

For browser applications, use Keycloak OIDC tokens:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

The token is validated against the Keycloak public key. User roles and brokerage assignments are extracted from token claims.

Roles & Permissions

Section titled “Roles & Permissions”

Full system access

  • Manage all brokerages and agents
  • Create/revoke API keys
  • Access data management tools
  • Configure system settings
  • View all leads and tours

Endpoints

Section titled “Endpoints”

Verify Authentication

Section titled “Verify Authentication”

Check if your credentials are valid and get user information.

GET /api/auth/verify

Response:

{
  "valid": true,
  "user": {
    "id": 123,
    "email": "agent@example.com",
    "role": "agent",
    "brokerage_id": 1,
    "agent_id": 45
  }
}

Get Current User

Section titled “Get Current User”

Get detailed information about the authenticated user.

GET /api/admin/me

Response:

{
  "authenticated": true,
  "user": {
    "id": 123,
    "email": "broker@example.com",
    "role": "broker",
    "brokerage_id": 1,
    "broker_id": 12,
    "agent_id": null
  }
}

Test Admin Access

Section titled “Test Admin Access”

Verify admin role is granted.

GET /api/admin/admin-test

Response (admin):

{
  "message": "You have admin access!",
  "user_email": "admin@example.com",
  "user_role": "admin"
}

Response (non-admin):

{
  "detail": "Admin role required"
}

Status: 403 Forbidden

Test Broker Access

Section titled “Test Broker Access”

Verify broker or admin role is granted.

GET /api/admin/broker-test

Response:

{
  "message": "You have broker access!",
  "user_email": "broker@example.com",
  "user_role": "broker",
  "brokerage_id": 1,
  "broker_id": 12
}

Public Endpoints

Section titled “Public Endpoints”

Some endpoints don’t require authentication:

  • GET /health — Health check
  • GET /api/properties — List properties
  • GET /api/public/* — Public brokerage/agent info
  • POST /api/contact — Submit contact form
  • POST /api/newsletter/subscribe — Newsletter signup
  • POST /api/tours — Request a tour

Error Responses

Section titled “Error Responses”

Missing Authentication

Section titled “Missing Authentication”
{
  "detail": "Not authenticated"
}

Status: 401 Unauthorized

Invalid API Key

Section titled “Invalid API Key”
{
  "detail": "Invalid API key"
}

Status: 401 Unauthorized

Insufficient Permissions

Section titled “Insufficient Permissions”
{
  "detail": "Admin role required"
}

Status: 403 Forbidden

Expired Token

Section titled “Expired Token”
{
  "detail": "Token has expired"
}

Status: 401 Unauthorized

Section titled “Related Resources”