Getting Started

This guide gets you to a working FerrisKey instance with your first authenticated user. You will start the Docker stack, create a realm, register a client, create a user, and request tokens.

Prerequisites

Docker and Docker Compose installed
A terminal and a web browser
Ports 3333 (API) and 5555 (UI) available

Deploy FerrisKey

Start the stack

Clone the repository and start all services:

git clone https://github.com/ferriskey/ferriskey.git
cd ferriskey
docker compose --profile registry up -d

This starts PostgreSQL, the FerrisKey API server, database migrations, and the admin console.

Verify the deployment

Wait a few seconds for migrations to complete, then check that all services are healthy:

docker compose --profile registry ps

The API is available at http://localhost:3333 and the UI at http://localhost:5555.

Log in to the admin console

Open http://localhost:5555 in your browser and sign in with the default credentials:

Username: admin
Password: admin

You’ll land in the master realm, the built-in realm that manages all other realms.

Change default credentials

The default admin credentials are for local development only. Change them immediately in any non-local environment by setting the ADMIN_USERNAME, ADMIN_PASSWORD, and ADMIN_EMAIL environment variables.

Create Your First Realm

A realm is an isolated tenant. Users, clients, roles, and credentials all live inside a realm.

Create a realm

In the admin console, navigate to Realms and click Create Realm. Give it a name like my-app and save.

Switch to the new realm

Use the realm selector in the sidebar to switch to my-app. All subsequent operations happen within this realm.

Register a Client

A client represents an application that uses FerrisKey for authentication.

Create a client

Navigate to Clients and click Create Client. Use these values:

Client ID: my-frontend
Client Type: Public (for a single-page application)
Redirect URIs: http://localhost:3000/*

Save the client.

Enable direct access grants

If you want to test authentication directly via the API (password grant), enable Direct Access Grants on the client settings page.

Create a User

Create a user

Navigate to Users and click Create User. Fill in:

Username: alice
Email: alice@example.com
First Name: Alice
Last Name: Smith

Save the user.

Set a password

On the user’s Credentials tab, set a password. Uncheck Temporary if you don’t want to force a password change on first login.

Authenticate

With direct access grants enabled, you can request tokens directly from the API:

curl -X POST http://localhost:3333/realms/my-app/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=my-frontend" \
  -d "username=alice" \
  -d "password=your-password"

The response contains an access_token, refresh_token, and optionally an id_token. That means the user authenticated successfully.

Connect a Real Application

The password grant above is useful for a quick API test. For real applications, use browser-based SSO with the OpenID Connect authorization code flow.

If you want to connect a dashboard, internal service, or self-hosted tool, follow the application SSO guide next. It shows which dashboard screens to use, what values to copy, and how to debug common setup mistakes.

What’s Next?

Core Concepts

Deep dive into realms, clients, users, roles, and tokens.

Connect an Application

Set up OpenID Connect SSO for an application with the FerrisKey dashboard.