API Authentication

Default Mode (Authentication Disabled)

Out of the box, Orchard runs with authentication disabled (orchard.security.oauth2.enabled: false). In this mode, all requests are permitted without a token.

To identify yourself to the server, pass your cultivator UUID in the X-Cultivator-Id header:

code

curl -H "X-Cultivator-Id: <your-uuid>" http://localhost:8080/api/groves

Your cultivator UUID is generated by trowel config init and stored in ~/.orchard/config.toml. Trowel sends this header automatically on every request.

OAuth2 / JWT (Production)

For production deployments, enable OAuth2 in application.yml:

code

orchard:
  security:
    oauth2:
      enabled: true
  issuer-uri: https://your-idp.example.com/realms/orchard

With OAuth2 enabled, the server validates JWT tokens from the configured issuer. Pass the token via the Authorization header:

code

curl -H "Authorization: Bearer <jwt-token>" http://localhost:8080/api/groves

Any OAuth2-compatible identity provider (Keycloak, Auth0, Okta, etc.) can be used as the issuer.

When OAuth2 is disabled, anyone with network access to the API can act as any cultivator by sending an arbitrary X-Cultivator-Id header. Always enable OAuth2 in production environments exposed to a network.

REST API Reference

Requirements