Quick Start

This guide will help you set up Frontier from scratch and create your first organization with a test user. You’ll learn how to install Frontier, configure dependencies, and verify everything works.

This guide assumes you’re starting fresh. If you already have Frontier installed, skip to Step 2.

Prerequisites

Before starting, ensure you have:

Docker and Docker Compose (recommended for quick setup)
PostgreSQL 13+ and SpiceDB (or use Docker Compose to run them)
Basic terminal/command line knowledge

Step 1: Install Frontier

Choose your installation method:

macOS
Linux
Windows
Docker

brew install raystack/tap/frontier

# Download and install .deb package
wget https://github.com/raystack/frontier/releases/latest/download/frontier_linux_amd64.deb
sudo dpkg -i frontier_linux_amd64.deb

scoop bucket add frontier https://github.com/raystack/scoop-bucket.git
scoop install frontier

docker pull raystack/frontier:latest

Verify the installation:

frontier --help

See the complete Installation guide for more options including Kubernetes deployment.

Step 2: Start Dependencies

Frontier requires PostgreSQL and SpiceDB. The easiest way to run them is with Docker Compose.

Clone the repository (optional)

If you want to use the provided Docker Compose configuration:

git clone https://github.com/raystack/frontier.git
cd frontier

Start PostgreSQL and SpiceDB

docker-compose up -d postgres spicedb

This starts:

PostgreSQL on port 5432
SpiceDB on port 50051

Verify services are running

docker-compose ps

Both services should show as “Up”.

Don't have Docker Compose?

If you prefer to run services manually:PostgreSQL:

docker run -d \
  --name frontier-postgres \
  -e POSTGRES_USER=frontier \
  -e POSTGRES_DB=frontier \
  -p 5432:5432 \
  postgres:13

SpiceDB:

docker run -d \
  --name frontier-spicedb \
  -p 50051:50051 \
  authzed/spicedb serve \
  --grpc-preshared-key "randomkey" \
  --datastore-engine memory

Step 3: Configure Frontier

Generate and customize the Frontier configuration file.

Initialize configuration

frontier server init

This creates a config.yaml file in the current directory.

Edit configuration

Open config.yaml and update the following settings:

config.yaml

version: 1

log:
  level: info

app:
  port: 8080
  grpc:
    port: 8081
  
  # For testing: bypass auth with email header
  # WARNING: Remove in production!
  identity_proxy_header: X-Frontier-Email

db:
  driver: postgres
  url: postgres://frontier:@localhost:5432/frontier?sslmode=disable
  max_query_timeout: 500ms

spicedb:
  host: localhost
  port: 50051
  pre_shared_key: randomkey
  fully_consistent: false

Run database migrations

frontier server migrate

This creates all required database tables.

The identity_proxy_header setting bypasses authentication and should only be used for local development and testing.

Step 4: Start Frontier Server

Launch the Frontier server:

frontier server start

You should see output like:

2024-03-03T10:30:15.123+0000    info    frontier starting {"version": "v0.11.3"}
2024-03-03T10:30:15.234+0000    info    Connected to spiceDB: localhost:50051
2024-03-03T10:30:15.345+0000    info    HTTP server listening on :8080
2024-03-03T10:30:15.456+0000    info    gRPC server listening on :8081

Keep this terminal open. Frontier logs will appear here.

Step 5: Create Your First Organization

Now let’s create an organization using the Frontier API.

Create organization

curl -X POST http://localhost:8080/v1beta1/organizations \
  -H "Content-Type: application/json" \
  -H "X-Frontier-Email: [email protected]" \
  -d '{
    "name": "Acme Corp",
    "title": "Acme Corporation"
  }'

Response:

{
  "organization": {
    "id": "org_1a2b3c4d5e6f",
    "name": "acme-corp",
    "title": "Acme Corporation",
    "created_at": "2024-03-03T10:30:20Z",
    "updated_at": "2024-03-03T10:30:20Z"
  }
}

Save the organization.id for the next steps.

Verify organization creation

List all organizations:

curl http://localhost:8080/v1beta1/organizations \
  -H "X-Frontier-Email: [email protected]"

Using the CLI instead

You can also use the Frontier CLI:

# Initialize CLI configuration
frontier config init

# Create organization
frontier organization create \
  --name "Acme Corp" \
  --header "X-Frontier-Email: [email protected]"

Step 6: Create a User

Create a user within your organization.

Create user

curl -X POST http://localhost:8080/v1beta1/users \
  -H "Content-Type: application/json" \
  -H "X-Frontier-Email: [email protected]" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "title": "Product Manager"
  }'

Response:

{
  "user": {
    "id": "user_7g8h9i0j1k2l",
    "email": "[email protected]",
    "name": "John Doe",
    "title": "Product Manager",
    "created_at": "2024-03-03T10:31:00Z",
    "updated_at": "2024-03-03T10:31:00Z"
  }
}

Add user to organization

curl -X POST http://localhost:8080/v1beta1/organizations/org_1a2b3c4d5e6f/users \
  -H "Content-Type: application/json" \
  -H "X-Frontier-Email: [email protected]" \
  -d '{
    "user_id": "user_7g8h9i0j1k2l",
    "role": "member"
  }'

Verify user membership

curl http://localhost:8080/v1beta1/organizations/org_1a2b3c4d5e6f/users \
  -H "X-Frontier-Email: [email protected]"

Step 7: Create a Project

Projects help organize resources within an organization.

curl -X POST http://localhost:8080/v1beta1/organizations/org_1a2b3c4d5e6f/projects \
  -H "Content-Type: application/json" \
  -H "X-Frontier-Email: [email protected]" \
  -d '{
    "name": "mobile-app",
    "title": "Mobile App"
  }'

Response:

{
  "project": {
    "id": "proj_3m4n5o6p7q8r",
    "name": "mobile-app",
    "title": "Mobile App",
    "org_id": "org_1a2b3c4d5e6f",
    "created_at": "2024-03-03T10:32:00Z"
  }
}

Step 8: Check Permissions

Verify that your setup is working by checking permissions.

curl -X POST http://localhost:8080/v1beta1/check \
  -H "Content-Type: application/json" \
  -H "X-Frontier-Email: [email protected]" \
  -d '{
    "resource": "org:org_1a2b3c4d5e6f",
    "permission": "view"
  }'

Response:

{
  "status": true
}

The permission check returns true because John is a member of the organization.

What’s Next?

Congratulations! You now have Frontier running with an organization, user, and project.

Setup Authentication

Configure OIDC providers like Google or GitHub

Define Roles & Policies

Create custom roles and access policies

Admin Portal

Access the web interface to manage resources

Integrate Billing

Set up Stripe integration and subscriptions

Configure Webhooks

Receive real-time event notifications

API Reference

Explore the complete API documentation

Common Next Steps

Setup SSO with Google

Configure Google OAuth for user authentication:

Create OAuth credentials in Google Cloud Console
Add OIDC configuration to config.yaml:

app:
  authentication:
    oidc_config:
      google:
        client_id: "your-client-id.apps.googleusercontent.com"
        client_secret: "your-client-secret"
        issuer_url: "https://accounts.google.com"

Restart Frontier server

See the OIDC Setup guide for detailed instructions.

Create Custom Roles

Define custom roles with specific permissions:

curl -X POST http://localhost:8080/v1beta1/roles \
  -H "Content-Type: application/json" \
  -H "X-Frontier-Email: [email protected]" \
  -d '{
    "name": "project-manager",
    "title": "Project Manager",
    "permissions": [
      "project.view",
      "project.update",
      "project.member.add"
    ]
  }'

Learn more in the Roles documentation.

Setup Billing with Stripe

Integrate Stripe for subscription management:

Get your Stripe API keys from the Stripe Dashboard
Configure in config.yaml:

app:
  billing:
    stripe:
      key: "sk_test_..."
      webhook_secret: "whsec_..."

Create products and plans

See the Billing Configuration guide.

Enable Audit Logging

Track all user actions and access events:

config.yaml

log:
  audit_events: db

View audit logs via API:

curl http://localhost:8080/v1beta1/audit-logs \
  -H "X-Frontier-Email: [email protected]"

Troubleshooting

Database connection errors

If you see database connection errors:

Verify PostgreSQL is running:
```
docker ps | grep postgres
```
Check connection string in config.yaml

Test connection:

psql postgres://frontier:@localhost:5432/frontier

SpiceDB connection errors

If authorization checks fail:

Verify SpiceDB is running:
```
docker ps | grep spicedb
```
Check host and pre-shared key in config.yaml

Test connection:

grpcurl -plaintext \
  -H "authorization: Bearer randomkey" \
  localhost:50051 \
  authzed.api.v1.SchemaService/ReadSchema

API returns 401 Unauthorized

Ensure you’re including the identity header:

-H "X-Frontier-Email: [email protected]"

This is required when identity_proxy_header is configured.

Need more help? Check the GitHub issues or start a discussion.

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

Prerequisites

Step 1: Install Frontier

Step 2: Start Dependencies

Step 3: Configure Frontier

Step 4: Start Frontier Server

Step 5: Create Your First Organization

Step 6: Create a User

Step 7: Create a Project

Step 8: Check Permissions

What’s Next?

Setup Authentication

Define Roles & Policies

Admin Portal

Integrate Billing

Configure Webhooks

API Reference

Common Next Steps

Troubleshooting

Build docs developers (and LLMs) love

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Prerequisites

​Step 1: Install Frontier

​Step 2: Start Dependencies

​Step 3: Configure Frontier

​Step 4: Start Frontier Server

​Step 5: Create Your First Organization

​Step 6: Create a User

​Step 7: Create a Project

​Step 8: Check Permissions

​What’s Next?

Setup Authentication

Define Roles & Policies

Admin Portal

Integrate Billing

Configure Webhooks

API Reference

​Common Next Steps

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Step 1: Install Frontier

Step 2: Start Dependencies

Step 3: Configure Frontier

Step 4: Start Frontier Server

Step 5: Create Your First Organization

Step 6: Create a User

Step 7: Create a Project

Step 8: Check Permissions

What’s Next?

Common Next Steps

Troubleshooting