Protect objects with Object Lock

Object Lock stops anyone deleting a version of an object before a date, its retention, or while it has a legal hold. Use it for backups that a stolen access key must not be able to wipe, and for records you have to keep for a set time.

You can turn Object Lock on only when you create a bucket. It keeps the bucket's versioning on for good (Keep earlier versions of objects), and you cannot remove it later.

• Sign in to the dashboard and open the service. The service must be active to create a bucket and to change a retention or a legal hold. You can read them in any status.
• Choose the mode before you lock anything (Modes). Compliance retention cannot be shortened, so a version under it stays, and is billed as stored data, until its date.

A retention has one of two modes:

Governance

Access keys cannot delete the version or shorten its retention. People who manage the service can shorten or remove the retention, or delete the version early, in the dashboard or through the API, after typing the version's name.

Compliance

Nobody can delete the version or shorten its retention before the date, in the dashboard, through the API or with an access key. You can only make it longer.

A legal hold has no date. While a version has one, nobody can delete it, whatever its retention says. People who manage the service put it on and take it off.

Retention and legal holds apply to one version. A new upload to the same key makes a new version with its own retention, and the older version keeps its own.

1. Open the service, select the Buckets tab, then select Create bucket….
2. Fill in Name and choose the Region (Create a bucket).
3. Tick Object Lock. Keep versions is ticked and greyed out, because Object Lock keeps versioning on.
4. Under Default retention, choose:
   • None, to lock only the versions you give a retention or a legal hold;
   • Governance or Compliance, to lock every new version for a set time. Type how long in Keep each new version for, and choose Days or Years in Unit: from 1 to 36,500 days, or from 1 to 100 years.
5. Select Create bucket.

A message confirms it, such as u7-ledger created. A lock marks the bucket in the list, and its header shows Object Lock.

Each new version gets the bucket's default retention when it is written, counted from that moment. This applies to uploads from the dashboard and from S3 clients alike. A year is 365 days.

The bucket's Settings tab shows the default on the Versioning and Object Lock card, such as Compliance, 7 years, or No default retention.

To change it:

1. On the bucket's Settings tab, select Change default retention….
2. Choose the mode and type the period.
3. Select Save retention.

A message confirms it, such as New versions in u7-ledger are locked: Compliance, 10 years. Versions that exist already keep the retention they have.

What you can change depends on the default you have:

• A compliance default can only be made longer, and it stays compliance. The dialog offers only Compliance, and a shorter period shows A compliance default can only be made longer than 2,555 days.
• A governance default can be made longer, or changed to compliance, straight away. To shorten it, or to remove it by choosing None, type the bucket's name and select Shorten retention or Remove retention.

1. Open the bucket's Objects tab and select the object's name. To lock an older version, select its date under Versions in the panel that opens.
2. In the Object Lock section, Retention shows the version's retention, such as Governance until and a date, or None. Select Set retention…, or Change retention… when it has one.
3. Under Mode, choose Governance or Compliance.
4. In Locked until, choose the date. The version stays locked to the end of that day, UTC.
5. Select Save retention.

A message confirms it, such as Locked until and the date. The date must be at least a minute ahead and at most 100 years ahead.

• Under compliance retention, the dialog offers only Compliance, and only dates from the current one on.
• Under governance retention, a date no earlier than the current one saves straight away, in either mode. An earlier date asks you to type the object's name and select Shorten retention.

1. Select Change retention…, then choose Remove retention.
2. Select Remove retention, type the object's name, and select Remove retention again.

A message confirms it: Retention removed. The lock ends in one minute. Once the minute has passed, the version can be deleted. Compliance retention cannot be removed.

1. Open the version's details, as in Lock one version.
2. In the Object Lock section, turn on Legal hold.

A message confirms it: Legal hold on. Nobody can delete this version until it comes off.

To take it off, turn off Legal hold and select Take hold off. A message confirms Legal hold off. A retention on the version still applies after the hold comes off.

Delete version…, in the version's menu with Show versions on or at the bottom of its details panel, checks the lock first:

• With a legal hold, it shows This version of dump.sql.gz has a legal hold. Take the hold off before you delete it.
• Under compliance retention, it shows This version of dump.sql.gz is under compliance retention until and the date, then Nobody can delete it before then.
• Under governance retention, the dialog warns Deleting it now overrides that retention. Type the object's name and select Delete anyway.

Once the retention ends and no hold is left, the version deletes as any other (Delete a version for good).

Delete object… and the other deletes in the object list only add a delete marker, which Object Lock allows. The object leaves the listing, and its locked versions stay under the marker.

An access key with Read and write permissions, whose scope covers the bucket, can upload to a locked bucket, and each new version gets the bucket's default retention. A delete-object without --version-id adds a delete marker, and a delete of an unlocked version works as on any bucket.

Access keys cannot change Object Lock. These answer 403 AccessDenied with every key:

• put-object-retention and put-object-legal-hold;
• put-object-lock-configuration;
• an upload that sets its own lock with --object-lock-mode, --object-lock-retain-until-date or --object-lock-legal-hold-status;
• a delete with --bypass-governance-retention.

Set retention and legal holds in the dashboard or through the API (With the API).

We refuse to delete a bucket while any version in it is under retention or has a legal hold, and we read every version's lock before we destroy anything. The message says how many versions are locked and when the last retention ends, such as u7-backups holds 3 locked versions, so it cannot be deleted yet. The last retention ends on 7 November 2026 at 14:00 UTC.

In a bucket with more than 10,000 versions, we delete the versions that are not locked and then refuse, and the message ends We deleted the and how many versions that were not locked.

To delete the bucket, wait for the last retention to end, take off every legal hold, and remove governance retention you no longer need. Then delete the bucket with its contents (Delete a bucket).

A bucket with Object Lock shows Object Lock in its header and a lock in the bucket list. Its Settings tab shows Object Lock as On with the default retention, and each version's details panel shows its Retention and Legal hold.

u7-assets was created without Object Lock. You can only turn Object Lock on when you create a bucket.

Create a new bucket with Object Lock ticked, and copy the objects into it with an S3 client.

Compliance retention can only be made longer. New objects in u7-ledger are kept for at least 2555 days in compliance mode.

A compliance default cannot be shortened, removed or changed to governance. Choose a period at least that long.

This version is under compliance retention until, then a date and Compliance retention can only be made longer.

Choose a later date in Locked until. Compliance retention cannot be shortened or removed.

This version has a legal hold, so nobody can delete it. Remove the hold first.

Turn off Legal hold in the version's details, then delete it.

The retention must end at least a minute from now.

Choose a later date in Locked until.

u7-backups holds 3 locked versions, so it cannot be deleted yet.

See Delete a bucket with Object Lock.

Change default retention…, Set retention… or Legal hold is greyed out or missing

The service is not active, or the bucket was created without Object Lock.

An S3 client gets AccessDenied setting a retention or a legal hold

Access keys cannot change Object Lock (Use Object Lock with an S3 client). Use the dashboard or the API.

Too many requests for this action. Try again later.

Your account made 300 versioning, retention and version changes in the last hour. Wait, then try again.

• Keep earlier versions of objects
• Create and delete buckets
• Create and revoke access keys
• How Object Storage is billed

Each request takes the service ID and the bucket ID, from GET /api/v1/client/object-storage/{service_id}/buckets. A service that is not Object Storage on your account answers 404 with Object storage service not found, and a bucket that is not on the service answers 404 with Bucket not found.

Add object_lock to POST /api/v1/client/object-storage/{service_id}/buckets. It takes mode, GOVERNANCE or COMPLIANCE, with days (1–36500) or years (1–100). An empty object_lock creates a lock with no default retention.

curl -X POST https://api.coritan.com/api/v1/client/object-storage/1207/buckets \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ledger", "object_lock": {"mode": "COMPLIANCE", "years": 7}}'

The new bucket has "versioning": "enabled" and its lock in object_lock:

{"enabled": true, "mode": "COMPLIANCE", "days": 2555, "years": 7}

days is always the period in days. years repeats it in years when it is a whole number of years, and is null otherwise. Every bucket in the list carries object_lock, with enabled false and the rest null when the bucket has no lock.

GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/object-lock returns the lock with the bucket_id:

{"bucket_id": 33, "enabled": true, "mode": "COMPLIANCE", "days": 2555, "years": 7}

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/object-lock changes it, and answers in the same shape. Send mode with days or years, or "mode": null to remove the default. To shorten or remove a governance default, add confirm with the bucket's name:

curl -X PUT https://api.coritan.com/api/v1/client/object-storage/1207/buckets/34/object-lock \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "GOVERNANCE", "days": 7, "confirm": "u7-backups"}'

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/retention takes:

key and version_id

The version. Without version_id, the current version.

mode and until

GOVERNANCE or COMPLIANCE, and the end as an ISO 8601 time, at least a minute and at most 100 years ahead. "mode": null removes governance retention, which then ends a minute later.

confirm

The object's name, the part of its key after the last /. Needed to shorten or remove governance retention.

curl -X PUT https://api.coritan.com/api/v1/client/object-storage/1207/buckets/34/objects/retention \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "db/dump.sql.gz", "mode": "GOVERNANCE", "until": "2027-03-31T23:59:59Z"}'

{
  "key": "db/dump.sql.gz",
  "version_id": "N1pQ7rS3tU5vW9xY2zA4bC6dE8fG0hJk",
  "retention": {"mode": "GOVERNANCE", "until": "2027-03-31T23:59:59Z", "active": true}
}

Read a version's details returns the same retention, with active false once the date has passed, and legal_hold.

PUT /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/legal-hold takes key, version_id and on:

curl -X PUT https://api.coritan.com/api/v1/client/object-storage/1207/buckets/34/objects/legal-hold \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "db/dump.sql.gz", "version_id": "N1pQ7rS3tU5vW9xY2zA4bC6dE8fG0hJk", "on": true}'

{"key": "db/dump.sql.gz", "version_id": "N1pQ7rS3tU5vW9xY2zA4bC6dE8fG0hJk", "legal_hold": true}

DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/version deletes a version under governance retention when the body adds "bypass_governance": true and confirm with the object's name:

curl -X DELETE https://api.coritan.com/api/v1/client/object-storage/1207/buckets/34/objects/version \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "db/dump.sql.gz", "version_id": "N1pQ7rS3tU5vW9xY2zA4bC6dE8fG0hJk", "bypass_governance": true, "confirm": "dump.sql.gz"}'

A version with a legal hold or under compliance retention answers 409 whatever the body says.

Where detail is an object, error is a code your program can test and message is a sentence you can show. Some carry more: locked_until, when a lock ends; confirm_word, the name to send as confirm; mode and days, the default a refusal keeps.