API Keys and Ceilings

An API key is a credential: a way for a request to prove which principal is calling. The identity itself — a human user or a service identity — is a principal, and it can hold authority, own resources, and outlive any particular key. A key is one way of authenticating as a principal, and a principal can have several of them at once.

Because a key is a credential rather than an identity, you can rotate keys without changing who owns anything, delete the person who issued a production key without breaking production, and hand an agent a key that can read exactly one space and nothing else.

What a Key Is Made Of

Every key records three distinct parties. They answer different questions and only one of them affects what the key can do.

The subject determines everything about the key's authority. A request made with the key runs as the subject, and OWN selectors resolve against the subject's resources. The creator is audit history. The owner controls the key as a resource but gains no access through it.

Because the subject is the identity and the key is only a credential, several keys can share one subject. This is what makes rotation ordinary: issue a second key for the same service identity, move your deployment to it, revoke the first. The workload's identity, ownership, grants, and roles never change.

Authority Modes

A key has one of two authority modes, fixed at issuance.

INHERIT_SUBJECT keys have no ceiling. They carry exactly the subject's current authority, whatever that happens to be at request time. Grant the subject something new and every inheriting key can use it immediately. Only a human can have an inheriting key, and only by issuing it for themselves. The key you receive when you redeem an enrollment is this kind.

SCOPED keys carry an immutable ceiling: a nonempty list of rules, each pairing an operation with a selector. The ceiling never grows, never shrinks, and never changes meaning. It sets an upper bound on what the key can do; a ceiling rule confers no authority of its own.

Service identities can only have scoped keys. A service identity accumulates authority over its lifetime, and a credential minted in its first week should not silently acquire everything granted to the identity in the years after. The ceiling pins each credential to what it was issued for.

The supported combinations are human/inheriting, human/scoped, and service/scoped.

How a Scoped Key Is Evaluated

A request made with a scoped key must pass two independent checks:

the subject's live authority allows (operation, target)
AND
the key's immutable ceiling allows (operation, target)

Each side is evaluated against the actual request. The two sides do not need to use the same selectors, and their intersection is computed per request rather than at issuance.

A worked example. Sarah's service identity prod-search holds a grant of READ_MEMORY with selector ANY — it may read any memory in the instance. Sarah issues it a key whose ceiling contains READ_MEMORY with selector DIRECT_MEMBERS_OF on the space support-tickets.

• The key can read memories directly contained in support-tickets. Both sides allow it.
• The key cannot read a memory in any other space. The subject's ANY grant allows it; the ceiling does not. Denied.
• If an administrator revokes that READ_MEMORY grant from prod-search, every read through the key fails from the next request on. The ceiling still permits support-tickets, but a ceiling is only an upper bound, and there is no longer any live authority underneath it.
• If the grant comes back, the key works again. Nothing about the key changed in either direction.

Removing subject-side authority therefore trims every key for that subject at once — except where some other live source, such as an all-authenticated grant, still permits the request. That is the tool for changing what an identity may do. Permanently retiring one particular credential is a different tool: revoke that key.

What It Takes to Issue a Key

Issuance is checked once, when the key is created. Every rule in the proposed ceiling must be covered by two things: the subject's current live authority, and the current effective authority of the request doing the issuing. Coverage is conservative:

• ANY covers any narrower selector for the same operation.
• OWN covers OWN, an EXACT rule for a resource the principal currently owns, and a DIRECT_MEMBERS_OF rule for a container it currently owns.
• EXACT covers only the same EXACT rule.
• DIRECT_MEMBERS_OF covers the same container rule, or an EXACT rule for one of the container's direct members.

If the issuing request itself runs on a scoped key, the child ceiling must also fit inside the issuing key's effective authority, and a scoped key can never mint an inheriting child. There is no way to issue a credential that escapes the ceiling of the credential that made it.

The checks bind only at issuance. Once a key is validly issued, later changes to the issuer's authority — or the issuer's deletion — do not retroactively revoke it. The key stands or falls with its subject.

Validity Windows

Every key has a valid_from instant, which defaults to the moment of issuance, and an optional expires_at. Eligibility is the half-open interval: the key works exactly at valid_from and stops working exactly at expires_at. A key with no expiration is bounded only by revocation and by the life of its subject.

Both bounds are immutable. To extend a key's life, issue a replacement and rotate to it.

Revocation Is Permanent

Setting a key's status to INACTIVE revokes it. There is no reactivation; the attempt fails with FAILED_PRECONDITION. Deleting a key also revokes it — the row is kept, and revoked keys remain visible in listings as history, with revoked_at and revoked_by_id recording what happened.

A key's effective status is computed at request time from the stored facts. At any moment a key authenticates only if all of these hold:

1. it has not been revoked;
2. the wall clock is inside its validity window; and
3. its subject is an active principal.

The third condition means deleting a principal disables all of its keys without marking any of them revoked. The keys' own lifecycle state stays truthful — nobody revoked them — they have no active subject to authenticate. The distinction matters for audit history and for nothing else: either way, the request gets UNAUTHENTICATED.

Where to Go Next

• Issue Scoped API Keys — the ceiling syntax and worked recipes.
• Set Up a Service Identity — production workloads with rotatable credentials.
• Operations and Selectors — the full operation catalog a ceiling can draw from.
• Security Model — where keys fit in the overall evaluation of a request.