Skip to content

Authentication

The RECreation API uses Keycloak for authentication via OAuth 2.0 / OpenID Connect. All requests must include a Bearer JWT token in the Authorization header.

Obtaining a Token

curl -X POST \
  "https://<keycloak-host>/realms/<your-realm>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=recreation" \
  -d "username=user@example.com" \
  -d "password=your_password"

import httpx

response = httpx.post(
    "https://<keycloak-host>/realms/<your-realm>/protocol/openid-connect/token",
    data={
        "grant_type": "password",
        "client_id": "recreation",
        "username": "user@example.com",
        "password": "your_password",
    },
)
token = response.json()["access_token"]

The response includes:

{
  "access_token": "eyJhbGci...",
  "expires_in": 300,
  "refresh_token": "eyJhbGci...",
  "token_type": "Bearer"
}

Using the Token

Include the token in every request:

curl https://<host>/core/api/communities \
  -H "Authorization: Bearer eyJhbGci..."

Token Refresh

Access tokens expire after 5 minutes. Use the refresh token to obtain a new one:

curl -X POST \
  "https://<keycloak-host>/realms/<your-realm>/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=recreation" \
  -d "refresh_token=<refresh_token>"

Token Expiry

Refresh tokens also expire (typically 30 minutes). If both tokens expire, the user must re-authenticate with credentials.