Help - OmegaSafe Documentation

Use this page to troubleshoot OmegaSafe behaviors in the account, API, CLI, and billing flows.

1. OmegaSafe Account
#

Accounts And Authentication
#

What should I do if my activation or reset email does not arrive immediately?
Wait 5 minutes and if the email does not arrive then retry the same flow later. This is the supported recovery path when email delivery is unsuccessfull.
Can I log in before activation?
No. The login route treats inactive accounts as unauthorized.
Registration or password-reset responses always look generic. Is that expected?
Yes. The unauthenticated user routes intentionally return the same outward response whether the email exists, does not exist, is inactive, or email delivery is being throttled. This avoids exposing account-existence signals.
What happens when MFA is enabled?
OmegaSafe API — POST /users/login returns 202 Accepted with an MFA challenge instead of a success token until OmegaSafe API — POST /users/login/mfa completes successfully.
How do I share a key with another user?
Use the signed-in key invitation flow rather than sharing credentials. Sharing is free: other users can use keys that you bill for without paying for those keys themselves; see Subscription Model — 3. Slot-Based Sharing Model. Open My Keys > View, choose Share, enter the recipient email and role, then create the invitation. The recipient signs in with that email, opens My Keys > My Invites, and accepts the invitation. This creates the External Claims Storage relation described in Keys Management — 4. Key Sharing Model, but it does not copy the Alpha onto the recipient’s device. To make the key actionable for that user, transfer the Alpha separately as described in Keys Management — 5. Alpha Distribution Requirement.

Billing And Account Changes
#

How to cancel subscription?
Open My Account > Billing & Subscription and cancel the active renewable plan there. If MFA is enabled on the account, the web app can require your current password and MFA code before the cancellation is accepted. See Terms and Conditions — 4.6 Cancellation.
What happens when I cancel auto-renewal?
See Subscription Model — 10. Cancellation.
How to deactivate my account?
Sign in to OmegaSafe Cloud, open My Account, and start the account deactivation action in the account UI. If the UI blocks the attempt, see the next question in this section.
Why can’t I deactivate my account yet?
Deactivation rules block the flow when any of these are still true:
- you have active auto-renewal; resolve this by following How to cancel subscription? above
- you are the billing user for any key; resolve this by deleting that key or transferring billing to another billing account as described in Keys Management — 6. Billing Transfer
- you own a storage mapped to a key; resolve this by deleting that key or moving it to another storage with OmegaSafe CLI — edit-key, following Keys Management — 8. Object-layout requirement for manual Delta migration
For the related billing and retention context, see Privacy Policy — How long do we keep your personal data?. In the account UI, the blocking reasons are shown after the deactivation attempt. Once those blocking reasons are cleared, you can retry immediately and deactivate the account.
How to delete my account?
The account will be deleted automatically after a cooldown period. For the automated removal timing after deactivation, see Privacy Policy — How long do we keep your personal data?. For privacy-rights requests related to personal-data deletion, see Privacy Policy — Your data rights under GDPR.
Why was a new subscription purchase rejected?
Causes include invalid billing fields, missing required invoice data, VAT-country-evidence failure, or an existing pending PayPal subscription flow.

2. OmegaSafe CLI
#

Distribute an OmegaSafe Key to Another Device
#

Use this guide when an existing OmegaSafe key should become usable on another device. OmegaSafe CLI treats a key as actionable only when the Alpha is present locally; the External Claims Storage relation and remote Deltas are not enough on their own. For the underlying requirement, see Keys Management — 5. Alpha Distribution Requirement.

On the target device, run omegasafe init so it has its own local configuration and protected containers.
Configure the same External Claims Storage connection on the target device before importing the key. You can create the connection again with OmegaSafe CLI — create-http-ecs, or export and import the existing External Claims Storage connection with OmegaSafe CLI — export-ecs and OmegaSafe CLI — import-ecs.

On a device where the key is already actionable, export the Alpha:

omegasafe export-key --key-uuid YOUR_KEY_UUID --output-path PATH_TO_EXPORTED_ALPHA

Transfer the exported Alpha file to the target device through a secure out-of-band channel you control. Treat the exported Alpha as highly sensitive key material.

On the target device, import the Alpha into the local CLI configuration:

omegasafe import-key --ecs-uuid YOUR_ECS_UUID --input-file PATH_TO_EXPORTED_ALPHA

After import succeeds, the key becomes locally actionable and the CLI reconciles missing Deltas through the configured External Claims Storage. Use OmegaSafe CLI — list-keys to confirm the key appears on the target device.

For another user’s device, first grant that user key access through the invitation workflow in Keys Management — 4. Key Sharing Model, then transfer the Alpha separately. Do not share External Claims Storage credentials with other users.

OmegaSafe API server Outage scenario
#

The OmegaSafe API server is down. What do I do? Uptime is really important to us, and we constantly work to improve our alerting and response time, as well as service resilience. However, unexpected events can happen, so we prepared this guide to help you understand the effects of outage and possible mitigation paths.
OmegaSafe CLI has built-in resilience against OmegaSafe API server outages through OmegaSafe CLI — OFFLINE Cache. Encryption can continue from local PERFORMANCE or OFFLINE claims, and decryption can continue when the required Delta is already local. A prolonged outage still matters when a flow has to contact Encryption Method — 11. External Claims Storage for fresh claims or missing Deltas.
OmegaSafe strongly recommends Bring Your Own Storage — 1. Recommendation so you keep access to authoritative encrypted Delta files you control. If you already use BYOS, the documented emergency local-file recovery path is OmegaSafe CLI — import-key-delta.
Follow this recovery sequence:
1. Decide whether the blocked operation is OmegaSafe CLI — encrypt or OmegaSafe CLI — decrypt.
2. If OmegaSafe CLI — encrypt is still satisfied by local PERFORMANCE or OFFLINE cache, continue working. If it now needs fresh claims from Encryption Method — 11. External Claims Storage, there is no documented manual claim-allocation bypass, so that encryption request remains blocked until the service returns. OmegaSafe monitors service health and will work on restoring the service as soon as possible.
3. If OmegaSafe CLI — decrypt fails because the required Delta is not locally on the device, first confirm this device already has the local Alpha and prior local ECS linkage for that key. The manual recovery path is not a bypass for keys that were never linked locally.
4. If the key uses OmegaSafe-managed internal storage, wait for the service to return. The documented manual recovery path depends on trusted Delta files you control in BYOS.
5. If the key uses BYOS, download the authoritative encrypted Delta files from your bucket.
6. Import only the next missing Delta at a time with OmegaSafe CLI — import-key-delta. That command enforces strict local sequence continuity, so each imported Delta must be exactly the next local sequence.
7. Retry OmegaSafe CLI — decrypt after the required Delta chain is local. When the service returns, use OmegaSafe CLI — pull-missing-deltas to reconcile any remaining newer Deltas.
Decryption CLI flow
```
  flowchart TD
      DECLOCAL{"Required Delta local?"} -->|Yes| DECCONT["Continue with decryption"]
      DECLOCAL -->|No| DECBYOS{"Using BYOS with trusted
Delta files?"}
      DECBYOS -->|No| DECWAIT["Wait for service recovery"]
      DECBYOS -->|Yes| DECCTX{"Local Alpha and prior ECS
link already present?"}
      DECCTX -->|No| DECNO["Manual Delta import unavailable"]
      DECCTX -->|Yes| DECIMPORT["Import next Delta from BYOS"]
      DECIMPORT --> DECCHAIN{"Required Delta chain complete?"}
      DECCHAIN -->|No| DECNEXT["Download next sequential Delta"]
      DECNEXT --> DECIMPORT
      DECCHAIN -->|Yes| DECRETRY["Retry decryption"]
      DECRETRY --> DECRECON["After recovery, run pull-missing-deltas"]
  
```
Encryption CLI flow
```
  flowchart TD
      ENCCACHE{"Local PERFORMANCE or
OFFLINE cache sufficient?"} -->|Yes| ENCCONT["Continue with local encryption"]
      ENCCACHE -->|No| ENCECS["Fresh ECS claim required"]
      ENCECS --> ENCBLOCK["Wait for service recovery"]
  
```
What are the public product and command names?
The product name is OmegaSafe CLI, and command examples use omegasafe.
Why does list-keys not show a key that exists remotely?
OmegaSafe CLI — list-keys shows only locally actionable keys. A key is actionable only when the local Alpha iteration is present. Import Alpha with OmegaSafe CLI — import-key to make that key actionable on the device.
Why does decryption fail with import guidance?
The required Alpha is not present locally, or the needed Delta has not been reconciled yet. Import Alpha first with OmegaSafe CLI — import-key, then let OmegaSafe CLI — import-key, OmegaSafe CLI — decrypt, or OmegaSafe CLI — pull-missing-deltas reconcile missing Deltas.
Can OmegaSafe CLI process arbitrarily large files without memory pressure?
Not yet according to the source docs. OmegaSafe CLI — encrypt and OmegaSafe CLI — decrypt currently load the relevant file payload into memory. The only published roadmap note is a future streaming fallback.
Where can I find OmegaSafe CLI usage docs?
See OmegaSafe CLI — 8. Command Reference.

3. OmegaSafe API
#

Why did a hybrid route return HTML instead of JSON?
Send Accept: application/json. Many public routes are hybrid, and Accept: */* is HTML-preferred.
Why did I get 406 Not Acceptable?
You requested the wrong mode for that route. Some routes are JSON-only, some are HTML-only, and some are hybrid.

What does the JSON error format look like?
JSON errors use the standard envelope with error_type, error_code, and error_description. See OmegaSafe API — 9. Error Handling.

{
  "error_type": "Not Found",
  "error_code": 404,
  "error_description": "Storage with storage_uuid=123e4567-e89b-12d3-a456-426614174000 was not found."
}

Where do I find endpoints and auth details?
See OmegaSafe API — 3. Authentication.

When is ALTCHA required?
#

Always on registration and password-reset routes, always on API-key generation in the account page, and on login after repeated failed attempts.

4. Documented Self-Help Checks
#

Before escalating an issue, the public docs support these checks:

for API calls, confirm Accept: application/json, auth method, and scope
for OmegaSafe CLI workflows, confirm the correct --config-dir and that Alpha exists locally
for BYOS, confirm the bucket still contains Deltas at the documented object layout
for download flows, confirm the release sha256 after download

1. OmegaSafe Account#

Accounts And Authentication#

Billing And Account Changes#

2. OmegaSafe CLI#

Distribute an OmegaSafe Key to Another Device#

OmegaSafe API server Outage scenario#

3. OmegaSafe API#

When is ALTCHA required?#

4. Documented Self-Help Checks#

5. Related Pages#