Auth Helpers

## The three places a credential block may sit A Postman collection is a JSON document. The **collection format** — the published schema, not the desktop app — decides which objects in that document may carry an `auth` member, and it allows exactly three: | Declaration site | The object it sits on | Typical use | | --- | --- | --- | | The collection | the top-level document | one scheme for every request in the file | | A folder | an `item-group` object | a subtree that talks to a different service | | A request | the `request` object | one endpoint that signs differently | At each of those sites the format writes `auth` as `oneOf` a `null` value or an auth object, and an auth object's only required member is `type`. Nothing else in the document may declare one: not a saved example, not a variable entry, not an event, not a header. That closed list is what makes the file tractable — when you want to know how a request signs, there are three kinds of place to look and no fourth. ## How a request finds the block that applies to it The **SDK** resolves this, not the format. `Item.getAuth()` runs a two-step lookup: 1. It extracts the `auth` from the item's own `request`. A block counts only if its `type` is a usable name; an absent block, or one whose `type` is `null`, does not count. 2. If the first step yields nothing, it calls `findInParents('auth', ...)`, which walks the parent chain outward and returns the `auth` of the **first** ancestor whose block passes the same test. The chain runs request, then the innermost enclosing folder, then each outer folder in turn, then the collection document. The walk stops the moment it finds a usable block, so the result is **nearest-wins**: - a request's own block beats every folder and the root; - an inner folder's block beats an outer folder's; - any folder's block beats the collection's; - if nothing in the chain declares one, `getAuth()` returns `undefined`. Two things the lookup does **not** do deserve stating plainly, because both are common assumptions. It does not **merge**: attributes are never combined across two levels, one block is chosen whole and the rest are ignored. And it does not apply a **default**: there is no implicit scheme filling the gap when every site is silent. An unresolved lookup simply means the runtime skips its authorization step and the request goes out as written. ## The empty-block rule The SDK deliberately refuses to build an auth object for a falsy value. Both the request and the folder constructors guard that assignment with the same comment — an empty auth "should not be created for falsy values **to allow inheritance from parent**". That one line is the whole design. If a falsy `auth` produced an empty object, the object would satisfy the lookup and silently sever the request from its ancestors' credentials. Because it produces nothing at all, a request that writes `"auth": null` stays transparent and the parent's block still applies. ## Why files that lean on inheritance read oddly The practical consequence is that **a request inheriting credentials and a request sending none look identical at the request**. Both carry no usable `auth` member. The difference lives entirely in the enclosing folders and the root, about which the request itself gives no hint. It is also why moving a request between folders can change how it authenticates with no edit to the request at all: position in the tree *is* the binding. When you inherit a collection you did not write, read outward rather than inward: 1. Look at the request's `auth`. If its `type` is a real name, you are done. 2. Look at the enclosing folder, then each folder above it, in order. 3. Look at the collection's top-level `auth`. 4. The first usable block on that path is the one that signs. Reach the top without one and nothing signs. ## Setting the block from code The SDK exposes the same three sites as methods. `Request.authorizeUsing(type, options)` installs a block on a single request, and `ItemGroup.authorizeRequestsUsing` is literally that same function bound onto a folder or a collection — so the identical call sets the block at whichever level you happen to hold. Passing `null` as the type is a special case: it deletes the `auth` property outright rather than storing an empty one, which restores inheritance for everything underneath. That symmetry is a useful mental model for the whole leaf — three sites, one selection rule, and a deliberate way to say "declare nothing here".