API docs by Redocly

HE Engine API (0.5.0)

Download OpenAPI specification:

URL: https://github.com/Yog-Sotho/Homomorphic-Encryption-Service License: MIT

A self-hosted engine for computing on encrypted data. Clients keep their TFHE client key; the server evaluates on ciphertexts with the server key they upload. Every error is {"error": {"code", "message"}}.

meta

Service status

Liveness: the process is up and answering.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "string"
}

Readiness: the database answers, both stores accept new files and every job worker is running. Only `200` means the instance should get traffic.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "checks": {
    },
  • "status": "ready"
}

he

Encryption parameters

The CRS proven inputs are made against, as `application/octet-stream`.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

What a client needs to produce compatible keys and inputs.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "config": "ConfigBuilder::default() + PARAM_PKE_MESSAGE_2_CARRY_2_KS_PBS_TUNIFORM_2M128",
  • "integer_type": "FheUint16",
  • "integer_types": [
    ],
  • "library": "TFHE-rs",
  • "max_batch_jobs": 0,
  • "max_ciphertext_bytes": 0,
  • "max_inputs": 0,
  • "max_job_input_bytes": 0,
  • "max_keys_per_user": 0,
  • "max_program_outputs": 0,
  • "max_program_steps": 0,
  • "max_server_key_bytes": 0,
  • "max_table_entries": 0,
  • "operations": [
    ],
  • "plaintext_modulus": 0,
  • "proofs": {
    },
  • "scheme": "TFHE (CGGI)",
  • "tfhe_version": "1.8.2"
}

auth

Accounts and sessions. Browser calls must come from an allowed Origin.

`POST /api/v1/auth/exchange` — redeems a one-time login code (once).

Authorizations:
None
Request Body schema: application/json
required
code
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "expires_in": 0,
  • "token": "string",
  • "user": {
    }
}

`POST /api/v1/auth/forgot-password`

Authorizations:
None
Request Body schema: application/json
required
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Starts GitHub sign-in.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Where GitHub returns the user after sign-in.

Authorizations:
None
query Parameters
code
string
state
string
error
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Starts Google sign-in.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Where Google returns the user after sign-in.

Authorizations:
None
query Parameters
code
string
state
string
error
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

`POST /api/v1/auth/login`

Authorizations:
None
Request Body schema: application/json
required
email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "expires_in": 0,
  • "token": "string",
  • "user": {
    }
}

`POST /api/v1/auth/logout` — ends this browser's session (its whole family).

Authorizations:
refresh_cookie

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

`GET /api/v1/auth/providers` — which sign-in buttons the frontend should show.

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "github": true,
  • "google": true
}

`POST /api/v1/auth/refresh` — exchanges the refresh cookie for a new access token and a new refresh cookie.

Authorizations:
refresh_cookie

Responses

Response samples

Content type
application/json
{
  • "expires_in": 0,
  • "token": "string",
  • "user": {
    }
}

`POST /api/v1/auth/register`

Authorizations:
None
Request Body schema: application/json
required
email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

`POST /api/v1/auth/resend-verification`

Authorizations:
None
Request Body schema: application/json
required
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

`POST /api/v1/auth/reset-password` — sets a new password (once per link) and signs out every session.

Authorizations:
None
Request Body schema: application/json
required
new_password
required
string
token
required
string

Responses

Request samples

Content type
application/json
{
  • "new_password": "string",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

`POST /api/v1/auth/verify` — confirms the email address and signs the user in.

Authorizations:
None
Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "expires_in": 0,
  • "token": "string",
  • "user": {
    }
}

user

The signed-in account

`DELETE /api/v1/user/account` — deletes the account and everything it owns.

Authorizations:
bearer
Request Body schema: application/json
required
password
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

`GET /api/v1/user/me` — the signed-in user, their sign-in methods and today's usage.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "daily_usage": {
    },
  • "email": "string",
  • "email_verified": true,
  • "has_password": true,
  • "id": "string",
  • "oauth_providers": [
    ]
}

`PUT /api/v1/user/password` — changes the password and signs out every session.

Authorizations:
bearer
Request Body schema: application/json
required
current_password
required
string
new_password
required
string

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

keys

Your TFHE server keys

`GET /api/v1/keys` — the caller's keys, newest first.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

`POST /api/v1/keys` — body is a `safe_serialize`d TFHE `CompressedServerKey`.

Authorizations:
bearer
Request Body schema: application/octet-stream
required

A safe_serialized TFHE-rs CompressedServerKey for the parameters of /he/params

string <binary>

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "has_public_key": true,
  • "id": "string",
  • "sha256": "string",
  • "size_bytes": 0,
  • "supports_compression": true,
  • "supports_proofs": true
}

`DELETE /api/v1/keys/{id}` — removes the key; its jobs stay but lose the reference.

Authorizations:
bearer
path Parameters
id
required
string

Key id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

`PUT /api/v1/keys/{id}/public-key` — body is a `safe_serialize`d TFHE `CompactPublicKey` made from the same client key as server key `id`.

Authorizations:
bearer
path Parameters
id
required
string

Key id

Request Body schema: application/octet-stream
required

A safe_serialized TFHE-rs CompactPublicKey (at most proofs.max_public_key_bytes)

string <binary>

Responses

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "has_public_key": true,
  • "id": "string",
  • "sha256": "string",
  • "size_bytes": 0,
  • "supports_compression": true,
  • "supports_proofs": true
}

jobs

Homomorphic computations

`GET /api/v1/compute/jobs?cursor=&limit=` — the caller's jobs, newest first.

Authorizations:
bearer
query Parameters
cursor
string

next_cursor of the previous page.

limit
integer <int32> [ 1 .. 100 ]

Jobs per page (default 20).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next_cursor": "string"
}

`POST /api/v1/compute/jobs` — queue `operation` on the encrypted inputs.

Honours an Idempotency-Key header: resending the same request with the same key returns the original job (with Idempotent-Replayed: true) instead of queuing and charging a second one.

Authorizations:
bearer
header Parameters
Idempotency-Key
string or null

1-255 visible ASCII characters. A retry with the same key and body returns the original job instead of queuing (and charging) another.

Request Body schema: application/json
required
compress_results
boolean

Return the results as one TFHE-rs CompressedCiphertextList (~2 KB) instead of one ciphertext each. Needs a key that supports_compression.

inputs
Array of strings

Standard base64 of safe_serialized ciphertexts of integer_type (e.g. FheUint16), encrypted with the client key that belongs to key_id.

integer_type
string (IntegerType)
Enum: "u8" "u16" "u32" "u64" "i8" "i16" "i32" "i64"

The inputs' type; u16 if absent.

key_id
required
string

One of the caller's registered server keys.

operation
required
string (Operation)
Enum: "add" "subtract" "multiply" "min" "max" "eq" "ne" "lt" "le" "gt" "ge" "sum" "program"

Homomorphic operations. Arithmetic wraps modulo 2^bits of the input type; comparisons return an encrypted boolean.

Every operation except Sum and Program takes two operands: two ciphertexts, or one ciphertext and a plaintext scalar as the right-hand side. Sum adds 2 to [MAX_INPUTS] ciphertexts. Program runs the job's Program on 1 to [MAX_INPUTS] ciphertexts.

Program (object) or null
proven_inputs
string or null

Standard base64 of one safe_serialized ProvenCompactCiphertextList encrypted under the key's public key, proven against the server's CRS with metadata he-engine/proof/v1/<key_id>.

scalar
string or null

A plaintext right-hand operand in decimal, e.g. "-7". The server sees it.

Responses

Request samples

Content type
application/json
{
  • "compress_results": true,
  • "inputs": [
    ],
  • "integer_type": "u8",
  • "key_id": "string",
  • "operation": "add",
  • "program": {
    },
  • "proven_inputs": "string",
  • "scalar": "string"
}

Response samples

Content type
application/json
{
  • "attempts": 0,
  • "compressed_results": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "input_bytes": 0,
  • "input_count": 0,
  • "integer_type": "u8",
  • "key_id": "string",
  • "operation": "add",
  • "program": {
    },
  • "proven": true,
  • "result_bytes": 0,
  • "result_type": "bool",
  • "result_types": [
    ],
  • "scalar": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "status": "pending"
}

`POST /api/v1/compute/jobs/batch` — queue several jobs at once, all or none.

With an Idempotency-Key, job i is keyed <key>/<i>: resending the batch returns the original jobs.

Authorizations:
bearer
header Parameters
Idempotency-Key
string or null

1-255 visible ASCII characters, for the whole batch. A retry with the same key and body returns the original jobs.

Request Body schema: application/json
required
required
Array of objects (CreateJobRequest)

1 to max_batch_jobs jobs, each as for POST /api/v1/compute/jobs.

Responses

Request samples

Content type
application/json
{
  • "jobs": [
    ]
}

Response samples

Content type
application/json
{
  • "jobs": [
    ]
}

`GET /api/v1/compute/jobs/{id}`

Authorizations:
bearer
path Parameters
id
required
string

Job id

Responses

Response samples

Content type
application/json
{
  • "attempts": 0,
  • "compressed_results": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "error_message": "string",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "input_bytes": 0,
  • "input_count": 0,
  • "integer_type": "u8",
  • "key_id": "string",
  • "operation": "add",
  • "program": {
    },
  • "proven": true,
  • "result_bytes": 0,
  • "result_type": "bool",
  • "result_types": [
    ],
  • "scalar": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "status": "pending"
}

`DELETE /api/v1/compute/jobs/{id}` — removes a job that is not running, with its stored ciphertexts.

Authorizations:
bearer
path Parameters
id
required
string

Job id

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

`GET /api/v1/compute/jobs/{id}/result` — an encrypted result as `application/octet-stream`: a `safe_serialize`d ciphertext of the type in `result_types[output]` (`FheBool` for comparisons), or, for a job with `compressed_results`, one `CompressedCiphertextList` of every result.

Authorizations:
bearer
path Parameters
id
required
string

Job id

query Parameters
output
integer >= 0

Which result (0-based; default 0), for a program with several outputs. A compressed job has one list holding them all: output 0.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}