Access Levels & Roles

AquaCloud uses Keycloak for identity and access management. Access to APIs, Swagger documentation, and background jobs is governed by group membership and tier-aware roles. This page summarizes the roles you will encounter, how farmer tiers work, and what each level can access.

Role overview

The platform derives a user's effective role from their Keycloak groups:

Access level	Keycloak mapping	Typical users	API access
admin	Member of /admin groups	AquaCloud staff, support engineers	Full access to v2 and v3 endpoints (including internal/admin tags) without extra headers.
premium_tier	Farmer under /farmers/* with the premium_tier role or tier attribute	Farmers with premium subscription	Direct access to /v2/** and /v3/** endpoints. No client secret needed for v3.
ordinary_tier	Farmer under /farmers/* without premium tier	Farmers on the ordinary subscription	/v2/** endpoints directly; /v3/** endpoints require the x-client-secret header issued for the integration.
customer	Member of /customers/*	Partners consuming curated datasets	Selected /v2/** endpoints (environment and mortality codelists). /v3/** endpoints are blocked.
verified	Authenticated user with verified email but no customer/farmer group	Early-stage testers, internal QA	Minimal read-only access (authentication endpoints + mortality category codelists).
public	No token or invalid token	Unauthenticated visitors	Can only request /v3/auth/token (or equivalent) to start an auth flow.

If a token does not map to any recognised group, the system assigns no_role and returns 403 Forbidden for protected routes.

Farmer tiers

Farmer identities live under the /farmers/{farmer_key} group tree. When a farmer authenticates, the backend resolves:

1. Farmer key – extracted from the group path or the group's key attribute.
2. Tier – determined from explicit Keycloak roles (premium_tier, ordinary_tier), group attributes (tier), or tier subgroups.

The tier drives access to analytics endpoints:

Capability	Ordinary tier	Premium tier
/v2/** endpoints	✅	✅
/v3/** endpoints without extra headers	❌	✅
/v3/** endpoints with valid x-client-secret	✅	✅
Swagger docs for /v3/**	Hidden by default	Visible
Upgrade requirement prompts	Yes (403 with guidance)	No

Client secret requirement

All v3 routers depend on auth_v3_with_client_secret:

1. Admins bypass the check.
2. Premium-tier farmers gain access without additional headers.
3. Ordinary-tier farmers must include x-client-secret: <secret> in every v3 request. The secret is issued per integration and should be kept server-side.

Failing to send the header results in 403 Premium tier or client secret required. An invalid secret returns 403 Access denied: Invalid client secret.

Premium-only endpoints

Some internal services use the stricter auth_require_premium_tier dependency. These routes return 403 Premium tier access required unless the farmer holds the premium tier. Contact AquaCloud if you need an upgrade to enable premium workloads.

Documentation filtering

The generated Swagger/OpenAPI explorer reflects your role:

• admin sees everything, including internal and metrics tags.
• premium_tier farmers see both v2 and v3 sections (Feeding, Environment, Inventory, Loss and Mortality, etc.).
• ordinary_tier farmers and customer users are limited to v2 tags.
• verified users only see authentication endpoints and mortality category reference calls.

This filtering helps avoid surfacing endpoints you cannot successfully call.

Best practices

• Store client secrets securely. Treat them like credentials; never embed them in frontend code.
• Monitor tier drift. If a farmer is moved between tiers in Keycloak, integrations do not require code changes—the backend detects the new tier automatically.
• Handle 403 errors gracefully. Surface clear upgrade prompts or support contact details when the API responds with tier-related errors.
• Request upgrades early. Premium analytics (v3) often power dashboards and benchmarking tools. Engage AquaCloud support if you anticipate needing premium access.