Encryption

Setup Enterprise Encryption

post

Setup Enterprise Encryption

This endpoint allows authenticated enterprise users to set up their encryption keys for securing data within the platform. It generates a cryptographic key hierarchy derived from a user-provided passphrase and establishes the necessary encryption infrastructure.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To set up encryption for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
encryption_secret	string	Yes	The passphrase used to derive the user's encryption keys. Must be kept secure and memorable.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Encryption keys have been successfully set up. Returns a confirmation message.
400	Bad Request - Encryption keys already exist for this user, the acting user is not in the owner's teams, or the authenticating API key doesn't have external usage permissions.
401	Unauthorized - Invalid or missing API key.
422	Validation Error - The request body contains invalid data.

---

Technical Process

The endpoint performs the following cryptographic operations:

1. Salt Generation: Creates a random 16-byte salt for key derivation

2. Key Derivation: Uses PBKDF2 to derive an X25519 keypair from the user's passphrase and salt

3. AES Key Generation: Creates a random 256-bit AES key (Key B) for data encryption

4. Ephemeral Encryption: Uses an ephemeral ECDH keypair to encrypt Key B with the user's public key

5. Secure Storage: Stores all cryptographic materials in base64-encoded format

---

Example Use Case

An enterprise user needs to initialize their encryption framework before storing sensitive data. They provide a strong passphrase which is used to derive their master encryption keys. The system generates the cryptographic infrastructure and stores the necessary components securely, enabling future encryption/decryption operations.

---

Example Request

POST /api/v2/encryption/setup HTTP/1.1
Host: api.example.com
Authorization: Bearer <ENTERPRISE_API_KEY>
accept_language: en-US
Content-Type: application/json

{
  "encryption_secret": "my_strong_encryption_passphrase_2024!",
  "acting_user_email": "[email protected]"
}

---

Example Response

{
  "detail": "Enterprise encryption keys successfully set up"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

encryption_secretstringRequired

acting_user_emailany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/encryption/setup

HTTPcURLJavaScriptPython

POST /api/v2/encryption/setup HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "encryption_secret": "text",
  "acting_user_email": "text"
}

No content

Check if the user has already set up encryption keys

get

Check Encryption Status

This endpoint allows authenticated users to check whether encryption keys have been set up for their account. It verifies if the cryptographic infrastructure required for enterprise encryption is properly configured and available.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To check encryption status for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Encryption keys are set up and ready for use. Returns a confirmation message.
400	Bad Request - Encryption keys are not set up for this user, the acting user is not in the owner's teams, or the authenticating API key doesn't have external usage permissions.
401	Unauthorized - Invalid or missing API key.
422	Validation Error - The request contains invalid parameters.

---

Example Use Case

An enterprise user or administrator wants to verify if encryption has been properly configured before attempting to encrypt sensitive data. They use this endpoint to check the encryption status and ensure the cryptographic infrastructure is in place for secure operations.

---

Example Request

GET /api/v2/encryption/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <ENTERPRISE_API_KEY>
accept_language: en-US

---

Example Response (Success - 200)

{
  "detail": "Encryption keys are properly set up"
}

Example Response (Error - 400)

{
  "detail": "No encryption keys found for this user"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

get

/encryption/status

HTTPcURLJavaScriptPython

GET /api/v2/encryption/status HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Verify if the user-typed secret is correct

post

Verify Encryption Secret

This endpoint allows authenticated users to verify if their provided encryption passphrase is correct. It attempts to re-derive the user's cryptographic keys and decrypt stored encryption materials to validate the secret's accuracy without exposing sensitive data.

---

Authentication

• Type: Bearer Token (API_KEY)

• Required: Yes

• Header: Authorization: Bearer <API_KEY>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To verify an encryption secret for an external user, the API key used for authentication must itself be configured for external usage (i.e., is_external_usage must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Body Parameters (JSON Schema)

Parameter Name	Type	Required	Description
encryption_secret	string	Yes	The passphrase to verify against the stored encryption keys.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - The provided encryption secret is correct and valid. Returns a confirmation message.
400	Bad Request - The secret is incorrect, encryption keys are not set up, the acting user is not in the owner's teams, or cryptographic data is missing/corrupt.
401	Unauthorized - Invalid or missing API key.
422	Validation Error - The request body contains invalid data.

---

Example Use Case

A user wants to confirm they remember their encryption passphrase correctly before attempting to encrypt or decrypt sensitive data. They provide their secret, and the system validates it against the stored cryptographic materials without exposing any keys.

---

Example Request

POST /api/v2/encryption/verify HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_API_KEY>
accept_language: en-US
Content-Type: application/json

{
  "encryption_secret": "my_encryption_passphrase_2024!",
  "acting_user_email": "[email protected]"
}

---

Example Response (Success - 200)

{
  "detail": "Encryption secret is valid"
}

Example Response (Error - 400)

{
  "detail": "Invalid passphrase"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/json

encryption_secretstringRequired

acting_user_emailany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/encryption/verify

HTTPcURLJavaScriptPython

POST /api/v2/encryption/verify HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "encryption_secret": "text",
  "acting_user_email": "text"
}

No content