AIOZ Storage Access Control: Macaroons and Access Grants

AIOZ Storage access control runs on macaroons: each access grant carries a bearer token whose caveats can narrow access but never widen it. The same grant also carries the key that decrypts your data, so you share both as one scoped, expiring credential.

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.

Updated Oct 29, 2026: a shorter answer-first opening, question headings, shorter sentences, a labelled diagram of an access grant, corrected wording on where grants are built and what members hold, and a closing section on how AIOZ Storage handles access control.

What controls access to your AIOZ Storage data?

Three pieces work together. Macaroons are the tokens that carry permissions, and access grants package a macaroon with an encryption key into one credential you can hand out. Sub-users, which the dashboard calls members, are standing team accounts with their own per-bucket permissions.

Once you see how the three fit, you know what AIOZ Storage can do for team access and where it stops today. The main gap is revocation: you can't yet revoke one derived credential without revoking its whole family tree.

What is a macaroon?

A macaroon is a bearer credential that you can narrow after it's issued, without calling a central server. Google researchers published the design in a 2014 paper to delegate smaller and smaller slices of access between parties. AIOZ Storage's docs describe the core property: "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 design is what separates a macaroon from an API key or a session cookie. A caveat is a restriction, such as an expiry time or a scope limit. You can keep adding caveats to narrow a macaroon, but the HMAC chain makes it infeasible to strip one off again. AIOZ's docs put the idea plainly: "Macaroons separate the policy (who can access what) from the mechanism (how the policy is enforced)." A static API key can't do this, because once issued it authorizes whatever it authorized from the start.

What is an access grant made of?

An access grant is AIOZ Storage's unit of shared access, and it bundles two keys into one credential. The eKey handles encryption, and the zKey handles authorization and is built as a macaroon. According to the docs, both keys are created on the client side.

Building one takes three steps:

1. Your client asks the server for a random ID, which becomes the macaroon's ID and is later used for validity checks and revocation. You add caveats, such as time limits and rights on specific buckets.
2. Your passphrase generates the eKey, using the mechanism from the encryption docs.
3. The two keys are combined into the access grant.

When you create S3 credentials from a grant, the grant is encrypted with your S3 Access Key ID and stored on the server. Only a client holding that Access Key ID can decrypt it again.

In practice, one access grant says both how to decrypt the data and what you may do with it. That's why the access grant tutorial has you tick a box confirming that AIOZ doesn't store or know encryption passphrases, which are essential for file access. When you hand out a grant, you hand out permission and the means to decrypt, for the bucket and duration you chose.

The dashboard lets you pick a credential type, S3 Credentials or CLI/API Key, and an expiry of 24 hours, 1 week, 1 month, 6 months, or 1 year. The docs list time restrictions among the caveats a macaroon can carry, which is how an expiry fits this model.

The permissions model: List, Write, Read, Delete

AIOZ Storage's permission system has 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, either a bucket or an object, with one or more of those actions. You build these rules on the client side instead of in a central policy console like AWS IAM. Time limits use the same caveat mechanism, so access can start at a set time or work only within a window.

This is a narrower action set than the AWS IAM permission list, and that's part of the point. Four bounded actions are easier to reason about than dozens of overlapping IAM permissions, though you lose some fine-grained control. Either way, the goal matches NIST's principle of least privilege: grant only the access a task needs. For the AWS side of that comparison, see bucket policy vs IAM policy, and for the theory, RBAC, ABAC and capability-based access control. The sister products scope credentials more simply: AIOZ Pin API keys carry a set of scopes, and AIOZ Stream API keys come in upload-only and full-access roles.

Members vs access grants: two ways to share access

AIOZ Storage gives you two tools for sharing access, and they solve different problems. A member is a standing sub-user account with a name of at least 8 characters, unique to your account. Its password needs at least 8 characters, including one uppercase letter and one digit. You assign it per-bucket permissions from the same List, Write, Read, Delete and All set, and you enter each bucket's passphrase when you assign it. A member exists until someone deletes it, and the dashboard shows the member's name for you to confirm first, because deletion can't be undone.

An access grant isn't an account. It's a scoped, time-boxed credential that you generate, hand out, and let expire on the schedule you set, from 24 hours up to 1 year. Use members for a team with long-term access needs, and walk through the screens in managing sub-users on AIOZ Storage. Use access grants when a contractor, a script or a one-off integration needs exact access for a limited time. To share a single object briefly, you can also sign a presigned URL for one object with the S3 credentials a grant gives you.

How access grant revocation works, and its current limits

AIOZ Storage separates a primary access grant from its children. You create a primary grant in the dashboard, and the server maps it to an ID it generated. Child grants are derived from a primary entirely on the client side, so AIOZ Storage isn't aware of them. To revoke a grant, you delete it in the dashboard, and revoking a primary makes the primary and every child derived from it invalid at once.

So today you can't revoke one child grant without revoking the whole tree under its primary. The docs state this openly: "In upcoming versions, we will introduce the capability to revoke specific access grants without the necessity of deleting the primary access grant." If you need to cut off one contractor while five others from the same primary keep working, plan for it up front. Keep each primary grant narrow enough that an all-or-nothing revocation is a blast radius you can accept.

How AIOZ Storage handles access control

We build access on capabilities rather than central policies. Your client creates the macaroon and the encryption key, and the dashboard turns the resulting access grant into S3 credentials with an access key, a secret key and an endpoint. Members cover people on your team, while grants cover code and short jobs, and both use the same four actions. To create, scope and delete grants step by step, follow the Manage Access Grants tutorial in the AIOZ Storage docs.

Frequently Asked Questions

What is a macaroon in the context of AIOZ Storage?
A macaroon is a bearer credential built from chained HMAC functions. You can add restrictions (caveats) to narrow what it authorizes, and the HMAC chain makes those restrictions infeasible to remove 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. An access grant bundles both into one credential, which is stored encrypted with your S3 Access Key ID.

How long can an AIOZ Storage access grant last?
You choose an expiry 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 a primary grant, because revoking the primary currently revokes every child derived from it. AIOZ's docs list per-child revocation as planned for a future version.

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

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

Related Reading

• How AIOZ Storage encryption works - the key derivation chain and encryption modes that access grants tie into through the eKey.
• 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 uses.
• How AIOZ Storage Pricing Works - what you pay for the storage and bandwidth these credentials use.
• RBAC vs ABAC vs Capability-Based Access Control Explained - the access-control model macaroons put into practice, with NIST's own definitions for the two alternatives.
• 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.
• Managing Team Access on AIOZ Storage: Inviting and Managing Sub-Users - the step-by-step wizard walkthrough for the member workflow this article introduces conceptually.
• Automating Backups to AIOZ Storage with GitHub Actions - scoping a narrow access grant specifically for a scheduled backup workflow's credentials.
• Bucket Policy vs IAM Policy: What Is the Real Difference? - the two AWS mechanisms this article's macaroon-based system replaces entirely with a different design.
• S3 Access Logs vs CloudTrail: Which Should You Use? - the separate question of recording what happened, downstream of the access-control model covered here.
• What an MCP server is and how super intelligence agents reach storage - giving an agent the narrowest access grant its tools need.
• AIOZ Storage Super Intelligence Memory: Record and Recall - a feature that authenticates every request with this same access-key and signing model.

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
• NIST CSRC Glossary: Least Privilege
• AIOZ Storage Documentation: Permissions
• AIOZ Storage Documentation: Revocation
• AIOZ Storage Documentation: Manage Access Grants