Keys Management

This page combines the key lifecycle guidance from OmegaSafe CLI and OmegaSafe API.

1. CLI Key Actionability Gate

#

OmegaSafe CLI treats a key as actionable only when its Alpha iteration is present locally. The Alpha is the initial key iteration (seq_number = 0) and is never distributed by ECS. Without the Alpha on the local device, the CLI cannot perform any key operations for that key UUID. For the underlying split model, see Encryption Method — Alpha and Delta Split.

The following commands all enforce this rule and fail with the same error when the Alpha is missing locally:

• view-key
• edit-key
• delete-key
• key-storage-limits

When the Alpha is missing, each of these commands fails with the following error message:

The Alpha for key_uuid {key_uuid} does not exist locally. You must obtain and import the Alpha key to the CLI by using 'import-key' command, to make the key actionable.

The list-keys command enforces the same rule by design: it only shows keys that have local Alpha presence. Keys that are registered on the ECS but whose Alpha has not been imported locally are intentionally hidden from the list output.

To make a key actionable on a new device or after a local configuration reset, use omegasafe import-key with the exported Alpha file and the ECS UUID where the key is registered. See OmegaSafe CLI — import-key for the full import-key command reference.

2. User-to-Key Roles

#

Each user-key relation has one of three roles: OWNER, MAINTAINER, or USER. The role belongs to that user’s relation to the key, not to the key object itself. Roles are cumulative — OWNER includes all MAINTAINER capabilities, and MAINTAINER includes all USER capabilities.

Roles are cumulative:

• MAINTAINER includes all USER capabilities.
• OWNER includes all MAINTAINER (and therefore USER) capabilities.

For the full API route reference for key operations, see OmegaSafe API — Keys API.

3. Unlink Matrix

#

The POST /keys/unlink route removes one relation between a user and a key. It does not delete the key itself. The same route is used for unlinking yourself and unlinking someone else; the submitted relation_uuid identifies which relation is being removed.

The following matrix documents who can unlink whom:

Role comparison for unlinking someone else is strict. Equal role is not enough, so an owner cannot unlink another owner, and a maintainer cannot unlink another maintainer.

Only owners can be billing users. Billing is assigned to the registering owner on key creation, and billing transfer can target only another owner.

For owner self-unlink, another owner must remain on the key, and the billing-user relation cannot be removed. If the owner is the billing user and wants to leave the key, they must first transfer billing to another owner using PATCH /keys/transfer_billing, then unlink themselves.

4. Key Sharing Model

#

Key sharing uses an invitation lifecycle. An OWNER or MAINTAINER creates an invitation for a target email address; the invited user accepts it to gain access to the key.

Who can create invitations and at what role level:

• OWNER can invite as OWNER, MAINTAINER, or USER
• MAINTAINER can invite as USER only
• The inviting user cannot grant a role higher than their own

Invitee account lifecycle:

• Invitations can be created before the invitee has an activated account. If the provided email does not belong to an existing account, or belongs to an existing but not yet activated account, the invitation is still created but the invitation email is not sent.
• The invited person can register or finish activation later using that same email address, then log in and view the invitation. In the signed-in UI, open My Keys > My Invites and look under Invitations for you.
• Until the account is activated, login is blocked, so the invitation cannot be viewed or accepted yet.
• The invited user must accept the invitation to gain access to the key.
• Invitation emails are sent only if the invitee account exists and is active.

Invitation lifecycle routes (see OmegaSafe API — Keys API for full request/response schemas):

• PATCH /keys/share — create an invitation (OWNER or MAINTAINER)
• GET /keys/invitations/list — list incoming and outgoing invitations
• POST /keys/invitation_accept — accept a pending invitation
• DELETE /keys/invitation_delete — delete a pending invitation (allowed if invitee, inviter, or key owner)

Share → Accept → Unlink flow:

Use the signed-in UI for the normal workflow. If you perform the workflow through the API instead, use Bearer auth (or an authenticated browser session cookie) for the share, accept, and unlink actions; those action endpoints do not accept API keys.

1. Share a key invitation.
   • UI: Open My Keys > View, find the key, choose Share, enter the recipient email and role, then submit Create invitation.
   • API: Call PATCH /keys/share.
2. Accept a received invitation.
   • UI: Open My Keys > My Invites, review Invitations for you, then choose Accept on the pending invitation.
   • API: Call GET /keys/invitations/list to read the pending invitation_uuid, then call POST /keys/invitation_accept.
3. Unlink a relation.
   • UI: To unlink yourself, open My Keys > View and choose Unlink on the key card. To unlink another user from a key you manage, open My Keys > View, choose Share, then use Unlink in Shared with.
   • API: Read relation_uuid from GET /keys/list or POST /keys/by_uuid, then call POST /keys/unlink.

This invitation flow covers only the ECS-side relation. For the separate requirement to transfer Alpha onto the recipient’s device, see Keys Management — Alpha Distribution Requirement.

5. Alpha Distribution Requirement

#

For HTTP ECS backends such as OmegaSafe Cloud today (or OmegaSafe Self-Hosted in the future) sharing the key in ECS is only one part of the process. That invitation flow creates the user-to-key relation in ECS, but it does not place the Alpha on the recipient’s device. Alpha distribution is excluded from ECS by design, to keep the actionable key only in environments entirely controlled by the user.

To make the shared key actionable on a new device, you must transfer the Alpha outside the system with OmegaSafe CLI — export-key and OmegaSafe CLI — import-key. See Encryption Method — ECS Backend Split Graph for the ECS backend overview.

Do not share ECS credentials with other users. Grant access through the invitation flow instead so permissions stay scoped to the specific key and role, access can be revoked cleanly, and broader ECS access is not leaked during handover.

6. Billing Transfer

#

Billing transfer lets the current billing user hand over responsibility for an existing shared key to another owner of that same key, without deleting the key for everyone else. This is especially useful when the current billing user wants to leave the key but cannot unlink themselves while the key is still assigned to their billing slot.

This transfer does not create any new paid capacity for the target user. It succeeds only if the target user already has an active subscription with at least one free billing slot, so the key moves onto capacity the target user already pays for.

All seven eligibility conditions must be met:

1. Requester is current billing user
2. Target user exists and is not requester
3. Target user account is activated
4. Target user is owner of this key. See Keys Management — User-to-Key Roles.
5. Target user is not in unpaid trial (is_on_trial check)
6. Target user has active subscription (billing_exp_ts not expired)
7. Target user has at least one free billing slot

Billing transfer route: PATCH /keys/transfer_billing

On success, the key billing owner changes and a notification email is queued for the target user with transfer details and remaining slots. See OmegaSafe API — PATCH /keys/transfer_billing for the full request/response schema.

7. Storage Ownership Model

#

Registration-time rule: At key registration time, storage_uuid can point only to the OmegaSafe Internal Storage or external storage owned by the authenticated user. Registration never places a new key directly onto another user’s storage.

Sharing does not transfer storage ownership: Sharing a key does not transfer storage ownership. A shared key may continue using OmegaSafe Internal Storage, storage owned by the billing owner, or storage owned by another member who previously reassigned the key. Collaborators who do not own the storage do not receive the bucket credentials.

Later-reassignment restriction: Later storage reassignment is stricter than registration. Only a key OWNER can change storage_uuid, and only to one of that owner’s own external storages. A MAINTAINER who submits storage_uuid to PATCH /keys/edit receives 403 Forbidden.

No return to internal storage: PATCH /keys/edit does not support moving a key back to OmegaSafe Internal Storage. Once a key has been moved to an external storage, the API cannot reassign it back to OmegaSafe Internal Storage.

When the OmegaSafe CLI edit-key command is used to change a key from Internal Storage to external storage, the CLI warns that OmegaSafe does not move Delta files and asks for confirmation unless --force is used. The warning also reminds that switching the key back to OmegaSafe Internal Storage is not supported by the API.

8. Object-layout requirement for manual Delta migration

#

Changing storage_uuid updates only key metadata in OmegaSafe. It does not copy, move, rename, or delete existing Delta objects in either the old or the new storage. Before changing storage, you must manually migrate the Delta files:

1. Download the existing Delta files from the current storage. In the OmegaSafe Cloud web interface, open the key’s Deltas page from the Keys list and use the Download button for each Delta. Via the API, call POST /deltas/download_url for each delta_uuid and download from the returned presigned URL.
2. Place the downloaded files into the target storage using the object layout that OmegaSafe expects. For the exact path format, UUID syntax, and examples, see Bring Your Own Storage — Object Layout.
3. Only after the Delta files already exist in the target storage should you call PATCH /keys/edit with the new storage_uuid.

9. delete-key Failure Isolation

#

The omegasafe delete-key command attempts ECS-side deletion (key record and Delta files from storage) but local cleanup always proceeds even if ECS is unavailable or the ECS deletion fails.

Specifically:

• The command requires local Alpha presence to treat the key as actionable. Missing local Alpha fails with the same actionable import-key guidance used by view-key.
• ECS deletion is attempted: the key record and Delta files are removed from ECS and the associated storage.
• For BYOS, storage credentials may intentionally omit delete permission. In that case, omegasafe delete-key is expected to handle the storage-side delete failure cleanly, complete the ECS/database-side removal, and clearly report whether any bucket objects remain for manual cleanup. See Bring Your Own Storage — DELETE Permission Is Optional.
• Local cleanup (local key iterations and cache entries) always runs regardless of whether ECS deletion succeeded or failed.
• On completion, the command prints: Delete-key completed for key <uuid>.
• Detailed ECS and local deletion diagnostics, including any partial-failure details, are produced through logging.

10. view-key Partial-Output Mode

#

The omegasafe view-key command returns partial output when ECS is unavailable, rather than hard-failing. In partial output mode, local sections remain populated from local key and cache sources, while ECS-related fields become null or empty and the status reflects the availability class.

Typical warning logs in partial output mode include:

• ExternalClaimsStorage <ecs_uuid> unavailable (...); result is partial.
• Key <key_uuid> missing data from ExternalClaimsStorage; result is partial.

Notable fields affected when ECS is unavailable:

• key_summary.external_claims_storage_status becomes one of "authentication error", "unreachable", or "unavailable"
• key_summary.key_name_ecs is null
• key_summary.latest_delta_capacity_left is null
• key_summary.total_key_encryption_capacity_left is null
• ecs_key_data.* fields are null
• deltas is []

Local sections (local_key_data, local_cache_data) remain populated for actionable keys. The external_claims_storage_name field is best-effort when ECS is unavailable, sourced from local ECS metadata if available.

See OmegaSafe CLI — view-key for the full view-key JSON payload schema including all fields, types, and nullability rules.

11. Immutable Local Name and ECS Name

#

OmegaSafe CLI resolves keys by key_uuid, not by name. The local key name stored in Alpha is immutable and remains the deterministic name shown in key_name_local and local_key_data.key_name. The mutable ECS name is shown separately in key_name_ecs and ecs_key_data.key_name.

The server-side name field is mutable ECS metadata that can be changed via PATCH /keys/edit or the web UI. Renaming it does not change key_uuid and does not rewrite local Alpha metadata on user devices. When ECS is unavailable, key_name_ecs and ecs_key_data.key_name become null rather than falling back to the local Alpha name.

12. Internal Storage Limits

#

If a key uses OmegaSafe Internal Storage, the current documented per-key limits are:

• uploads: daily=2, monthly=5, stored=15
• downloads: daily=20, monthly=200

These aggregate count limits apply only to keys using OmegaSafe-managed internal storage. Keys using user-provided storage (Bring Your Own Storage) are not subject to these aggregate limits. Every individual Delta upload is limited to 10 MiB and uses write-once, checksum-enforced signed PUT safeguards for both storage models. See Bring Your Own Storage — Delta Upload Safeguards and Bring Your Own Storage — Internal Storage Limits.

Check internal storage usage from OmegaSafe CLI with:

omegasafe key-storage-limits --key-uuid YOUR_KEY_UUID --json

You can check the same limits via OmegaSafe API — POST /keys/internal_storage_limits. API key authentication is allowed with the keys:read scope.

curl -X POST https://app.omega-safe.com/keys/internal_storage_limits \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "key_uuid": "234e5678-e89b-12d3-a456-426614174001"
  }'