AIOZ Storage Access Control: Macaroons and Access Grants

Hand someone an AIOZ Storage access grant, and you are handing them a macaroon: a bearer token that can be narrowed down after the fact without ever calling AIOZ's servers to check. That is a different foundation than the static API keys most S3-compatible storage still runs on, and it changes what you can and cannot do when you need to share, scope, or pull back someone's access. This article covers how macaroons actually work, how AIOZ Storage's access grants combine encryption and authorization into one credential, how the four-action permissions model works, and where the current limits of that system sit.

TL;DR:

• AIOZ Storage governs access through macaroons, bearer tokens with cryptographically enforced caveats.
• Access grants package an encryption key and an authorization key into one shareable credential.
• Revoking a primary access grant currently revokes everything derived from it, all or nothing.

What Controls Access to Your AIOZ Storage Data?

Three mechanisms working together: macaroons, which are the underlying cryptographic tokens that carry permissions; access grants, which package a macaroon-based authorization key together with an encryption key into one credential you can hand out; and sub-users, which are persistent team-member accounts that hold their own set of access grants. Understanding how these three fit together explains both what AIOZ Storage can do for team access control and where it currently cannot go further, like revoking one derived credential without killing its whole family tree.

Macaroons: The Cryptographic Tokens Behind Every Permission

Macaroons are a bearer-credential design first published by Google researchers in a 2014 paper, built to solve a specific problem: how do you delegate narrower and narrower slices of access to other parties without contacting a central server every time. AIOZ Storage's documentation describes them directly: "Macaroons are efficient as they carry their own cryptographic proof of authorization. Their caveats are constructed using chained HMAC functions, allowing easy addition of caveats while preventing their removal."

That chained-HMAC construction is what makes macaroons different from a typical API key or session cookie. A caveat is a restriction, like an expiration time or a scope limit, and you can keep adding caveats to a macaroon to narrow what it can do, but the chained-HMAC structure makes it cryptographically infeasible to strip a caveat back off. AIOZ's docs put the underlying idea plainly: "Macaroons separate the policy (who can access what) from the mechanism (how the policy is enforced)." A static API key cannot do this. Once issued, it authorizes whatever it originally authorized, full stop.

What Is an Access Grant? eKey, zKey, and a Single Shareable Credential

An access grant is AIOZ Storage's actual unit of shared access, and it bundles two different keys into one artifact: an eKey, which handles encryption, and a zKey, which handles authorization and is built as a macaroon. Creating one is a three-step process on AIOZ's side: the client requests a random ID from the server that becomes the macaroon's ID (used later for validity checks and revocation), the eKey gets generated, and the two are combined into the finished access grant. That finished grant is then encrypted using your S3 Access Key ID and stored server-side, decryptable only by a client that holds the matching Access Key ID.

In practice, this means a single access grant carries both "here is how to decrypt this data" and "here is what you are allowed to do with it," which is why AIOZ's own documentation is direct about the tradeoff: "AIOZ does not store or know encryption passphrases. The passphrase is essential for file access." Hand out an access grant, and you have handed out both permission and the means to decrypt, together, for exactly the bucket and duration you scoped it to.

Generating one through the dashboard gives you a choice of credential type, S3 Credentials or CLI/API Key, and lets you set an access expiration window: 24 hours, 1 week, 1 month, 6 months, or 1 year. That expiration is itself a caveat baked into the macaroon, not a separate setting bolted on top.

The Permissions Model: List, Write, Read, Delete

AIOZ Storage's permission system is built from exactly four actions: List (list buckets or objects), Write (write into a bucket), Read (read objects), and Delete (delete objects). A permission rule pairs a subject, a bucket or an object, with one or more of those actions, and these rules are constructed on the client side rather than centrally managed the way an IAM policy console usually works. Time constraints, like the expiration windows mentioned above, get layered on through the same caveat/attenuation mechanism that macaroons use generally, not a separate scheduling system.

This is a narrower action set than AWS IAM's granular permission list, and that is arguably the point: four clearly bounded actions are easier to reason about than dozens of overlapping IAM permissions, at the cost of less fine-grained control if your use case needs something IAM-style policies would normally express in more detail.

Members vs Access Grants: Two Different Ways to Share Access

AIOZ Storage gives you two distinct tools for sharing access, and they solve different problems. A member is a persistent sub-user account: a name (at least 8 characters, unique to the account), a password (at least 8 characters with at least one uppercase letter and one digit), and a per-bucket permission assignment from the same List/Write/Read/Delete/All set, plus its own bucket passphrase. Once created, a member exists until someone deletes it, and deletion shows a confirmation dialog with the member's name before you click through, since it is permanent and non-undoable.

An access grant, by contrast, is not an account. It is a scoped, time-boxed credential you generate and hand out, expiring on the schedule you set (24 hours up to 1 year) rather than persisting indefinitely. Use members when you have an actual team with recurring, long-term access needs. Use access grants when you need to hand a contractor, a script, or a one-off integration exactly the access it needs for exactly as long as it needs it, and nothing more by default.

How Access Grant Revocation Works (and Its Current Limits)

AIOZ Storage distinguishes between a primary access grant, created through the Admin Console with a server-generated ID, and child access grants, which get derived from a primary one entirely on the client side. That client-side derivation has a real consequence: AIOZ Storage has no visibility into child access grants until the moment someone revokes the primary, at which point every child derived from it becomes invalid at once, along with the primary itself.

There is currently no way to revoke a single child access grant without revoking the entire tree beneath its primary. AIOZ's own documentation states this as a known gap, not a hidden limitation: "In upcoming versions, we will introduce the capability to revoke specific access grants without the necessity of deleting the primary access grant." If your access control plan depends on revoking one contractor's credential while five others derived from the same primary keep working, that capability does not exist yet, and today's workaround is to structure your primary access grants narrowly enough from the start that an all-or-nothing revocation is an acceptable blast radius.

Frequently Asked Questions

What is a macaroon in the context of AIOZ Storage?
A macaroon is a bearer-token credential built from chained HMAC functions, which let you add restrictions (caveats) to narrow what it authorizes, while making it cryptographically infeasible to remove those restrictions afterward.

What is the difference between an eKey and a zKey?
The eKey handles encryption, and the zKey handles authorization and is built as a macaroon. AIOZ Storage's access grant bundles both into a single credential, encrypted using your S3 Access Key ID.

How long can an AIOZ Storage access grant last?
You choose an expiration when you create one: 24 hours, 1 week, 1 month, 6 months, or 1 year.

Can I revoke just one access grant without affecting others?
Not if it was derived as a child of the same primary access grant. Revoking a primary currently revokes every child derived from it. AIOZ's documentation lists granular per-child revocation as a planned future release, not something available today.

Should I create a member account or an access grant for a new collaborator?
Use a member account for long-term team access that needs its own login. Use an access grant for scoped, time-limited access, like a contractor engagement or a script integration, that should expire automatically.

What actions can an AIOZ Storage permission rule grant?
Exactly four: List, Write, Read, and Delete, applied to a specific bucket or object as the subject.

Related Reading

• How AIOZ Storage Encryption Actually Works - the key derivation chain and encryption modes that access grants tie into through the eKey.
• Zero-Knowledge Encryption: AIOZ Storage Can't See Your Data - why AIOZ never holds your bucket passphrase, and how that connects to access grant security.
• AIOZ Storage Explained: S3-Compatible Decentralized Storage - what AIOZ Storage is overall, including its official pricing and account limits.
• Migrate from Amazon S3 to AIOZ Storage with rclone - generating the S3 Credentials access grant this migration actually uses.
• How AIOZ Storage Pricing Works - why this access-control model is the differentiator AIOZ Storage leans on against cheaper competitors.
• AIOZ Storage Glossary: Bucket, Passphrase, Macaroon - quick definitions for macaroon, caveat, eKey, zKey, and sub-user, all covered in depth in this article.
• Migrate from Backblaze B2 to AIOZ Storage with rclone - generating the S3 Credentials access grant this migration path also uses.
• File Management API with FastAPI, Boto3, and AIOZ Storage - the same access grant credentials, wired into a working Python API instead of a CLI migration.

References

• Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud (Google Research, NDSS 2014)
• AIOZ Storage Documentation: Macaroons
• AIOZ Storage Documentation: Access Grant