Skip to content

REST API Authentication ​

rekuiper supports JWT RSA256 authentication for management REST APIs when enabled.

To enable authentication:

  1. Place your RSA public key file in the etc/mgmt directory.
  2. Sign your JWT tokens using the matching RSA private key.
  3. Include the token in HTTP request headers:
http
Authorization: <JWT_TOKEN>

If the token validates successfully, the server processes the request. If validation fails, the server returns HTTP status code 401 Unauthorized.

JWT Header ​

json
{
  "typ": "JWT",
  "alg": "RS256"
}

JWT Payload Claims ​

The JWT payload must use the following claim schema:

ClaimRequiredDescription
issYesIssuer. Must match the filename of the public key stored in etc/mgmt.
audYesAudience. Must be set to eKuiper.
expNoExpiration timestamp in Unix epoch seconds.
jtiNoUnique JWT identifier.
iatNoIssuance timestamp in Unix epoch seconds.
nbfNoNot-before timestamp in Unix epoch seconds.
subNoSubject identifier.

Example payload:

json
{
  "iss": "sample_key.pub",
  "aud": "eKuiper"
}

Ensure that the public key file sample_key.pub exists in the etc/mgmt directory.

JWT Signature ​

Sign the token using your RSA private key. rekuiper verifies the signature against the matching public key located in etc/mgmt.

Coexistence with Console Password and Fleet Token ​

When basic.authentication: true is enabled alongside uiPassword or fleetToken:

  • RS256 JWT Tokens: Accepted in the Authorization header (either raw <JWT_TOKEN> or Bearer <JWT_TOKEN>).
  • Web Console Password (uiPassword): Requests carrying Authorization: Bearer <uiPassword> are verified using constant-time byte comparison and permitted for Web Console sessions.
  • Fleet Control Plane Token (fleetToken): Requests to /fleet/* or /api/v1/fleet/* carrying Authorization: Bearer <fleetToken> or X-Fleet-Token: <fleetToken> are verified in constant time.
REST API Authentication Guard (auth_guard)Incoming HTTP RequestAuthorization Headeror X-Fleet-TokenPublic: /, /ping, /ui, /ui/authCredential Verification Pipeline1. Fleet Route Check: Constant-Time fleetToken Match2. Console Bearer Check: Constant-Time uiPassword Match3. JWT Guard: RS256 Signature & Claims (etc/mgmt/*.pub)Zero Timing Side-Channels (constant_time_eq)Protected Route HandlerValid: 200 OK / Route ExecutionInvalid: 401 Unauthorized

rekuiper is open source (Apache-2.0 / MIT) · For an all-in-one MQTT broker with embedded rekuiper rules, see IndraMQTT.