Module helvetia::api

Helvetia API

This module contains the API logic of Helvetia, which is basically a thin layer over Helvetia's Vault. We use warp for the handling of HTTP requests/responses and serde for the (de)serialization of JSON strings.

API calls

All API calls expect the header Helvetia-Token, with the token for each operation. If the header is not provided, the request will fail with 401 Unauthorized. Also, all request data are in JSON format so make sure to encode any binary payloads first, e.g., in Base64.

Below is a list of the supported API calls. We use the v0/ prefix because the API is not finalized yet, and things may break.

PUT v0/secrets/{secret}

Create or replace a secret with name {secret}.

Request

Expects the following request body in JSON:

{
    "owner_token": string,
    "meta_token": string, // optional
    "data": string,
    "meta": string,  // optional
}

Response

Returns 204 No Content for successful operations. Else, returns one of the following error codes:

• 400 Bad Request:
  • When a required field is not present in the request body, or is empty.
  • When the request body is not valid JSON.
• 401 Unauthorized: When the Helvetia-Token header is not provided.
• 403 Forbidden: When Helvetia-Token does not match the stored token.
• 411 Length Required: When the Content-Length header is missing.
• 413 Payload Too Large: When the request body is larger than a deployment-specific limit.

GET v0/secrets/{secret}/data

Get the data of a secret with name {secret}.

Response

Returns 200 OK for successful operations, with the secret's data in the response's body. Else, returns one of the following error codes:

• 401 Unauthorized: When the Helvetia-Token header is not provided.
• 403 Forbidden: When Helvetia-Token does not match the stored token.
• 404 Not Found: When the secret with name {secret} does not exist.

GET v0/secrets/{secret}/meta

Get the metadata of a secret with name {secret}. For this operation and only, the user can provide the metadata token.

Response

Returns 200 OK for successful operations, with the secret's metadata in the response's body. Else, returns one of the following error codes:

• 401 Unauthorized: When the Helvetia-Token header is not provided.
• 403 Forbidden: When Helvetia-Token does not match the stored token.
• 404 Not Found: When the secret with name {secret} does not exist.

DELETE v0/secrets/{secret}

Delete a secret with name {secret}.

Response

Returns 204 No Content for successful operations. Else, returns one of the following error codes:

• 401 Unauthorized: When the Helvetia-Token header is not provided.
• 403 Forbidden: When Helvetia-Token does not match the stored token.
• 404 Not Found: When the secret with name {secret} does not exist.

Structs

Handlers	The handlers for each API request.
PutSecretReq	The JSON body of the PUT request.

Constants

HELVETIA_TOKEN_HEADER

The name of the HTTP header for the Helvetia token.

Functions

routes

Constructor for warp routes.