Skip to content

docs: document master and keycloak API branches #608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hariclerry wants to merge 1 commit into
base: keycloak
Choose a base branch
from
Open

docs: document master and keycloak API branches #608

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 40 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,18 +178,55 @@ If you have not installed db-migrate globally, while in the database folder, you

See here to learn more about db-migrate: https://db-migrate.readthedocs.io/en/latest/

# Branches and Authentication

# Keycloak and Access Key Setup
This repository currently maintains two API variants. They use the same codebase and
database, but they authenticate requests differently and are deployed under different
paths.

| Branch | Deployed API path | Authentication |
| ---------- | ------------------ | ------------------------------------------------------------------- |
| `master` | `/wallet/v2` | API-issued JWT plus the `treetracker-api-key` header |
| `keycloak` | `/wallet/keycloak` | Keycloak access token verified against the realm's JWKS; no API key |

The `master` branch is the legacy v1/v2 API. It verifies JWTs signed by the wallet
API's configured `PRIVATE_KEY` and `PUBLIC_KEY` values and identifies the wallet
directly from the token.

## Overview
The `keycloak` branch is used by the current wallet app. Keycloak handles login and
issues the access token. The API verifies that token, reads the Keycloak account ID,
and maps it to one or more wallets through `keycloak_account_id`.

Keycloak is used for authentication and authorization in this project. For an excellent introduction to Keycloak, watch this video: https://www.youtube.com/watch?v=fvxQ8bW0vO8
Both branches connect to the same PostgreSQL database. A schema, migration, or test
data change made through one branch can therefore affect the other branch. Check the
target branch before changing database behavior.

You can identify the deployed variant with unauthenticated requests:

```bash
curl -i https://dev-k8s.treetracker.org/wallet/v2/wallets
# master: requires the treetracker-api-key header

curl -i https://dev-k8s.treetracker.org/wallet/keycloak/wallets
# keycloak: requires a Keycloak bearer token
```

Based on the current deployment setup, new web-wallet-app features and fixes should
normally branch from `keycloak` and target `keycloak`. Changes specifically intended
for the legacy API should target `master`.

NB: Confirm the target branch with maintainers
before starting work, especially for changes affecting shared database tables or
migrations, and review compatibility with both variants.

# Keycloak and Access Key Setup

@Kpoke Kpoke Oct 6, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was something meant to be here?

Also. maybe update docker-compose to support keycloak as well, and the documentation on how to go about that, including getting tokens, so a user can just run docker compose and have everything set up locally


## Overview

Keycloak is used for authentication and authorization in this project. For an excellent introduction to Keycloak, watch this video: https://www.youtube.com/watch?v=fvxQ8bW0vO8

## Development Environment

- Contact the admin team for login credentials

## Generate an access token using curl:
Expand All @@ -205,7 +242,6 @@ curl --location 'https://dev-k8s.treetracker.org/keycloak/realms/treetracker/pro

```


### Running Scripts

#### To create a new wallet:
Expand Down