skip to content

In a saved Postman collection, how does the `auth` object name a scheme and where do its settings live?

level: juniorimportance: must knowfreq 68%

answer

  1. One selector, several parallel settings arrays
  2. The scheme name appears twice in the object
  3. Settings are key/value attributes, not declared fields
  4. Only one member of auth is required
  5. parameters() reads this[this.type]

basics

~10 s

The auth object's required type field names the scheme, and that scheme's settings sit in a sibling array with the same name, holding auth attributes. Only key is required on each attribute.

solid answer

~40 s

The collection format declares `auth` as an object whose only required member is `type`, a string naming the scheme. The settings for that scheme sit in a **sibling array under the same name**, so `"type": "basic"` pairs with a `basic` array. Each entry in that array is an auth attribute: an object with a required `key`, a `value` declared with no type at all, and an optional `type` string of its own. Because the parameter arrays are keyed by name rather than nested under the selector, one `auth` object can carry populated arrays for several schemes at once and the top-level `type` picks which one is live. The SDK's `RequestAuth.parameters()` returns exactly `this[this.type]`, so the unselected arrays are inert but preserved across a round trip.

code

json · 12 lines
json
{
  "auth": {
    "type": "basic",
    "basic": [
      { "key": "username", "value": "jane" },
      { "key": "password", "value": "s3cret" }
    ],
    "digest": [
      { "key": "realm", "value": "items.x" }
    ]
  }
}

go deeper

for a junior

Be ready to point at a saved auth block and say which field selects the scheme and which array holds its settings. Knowing that the scheme name appears twice is most of the answer.

for a middle

Explain why the settings are a list of key/value attributes rather than declared fields, and what that buys the format when a scheme gains a parameter.

for a senior

Show that you have noticed abandoned scheme arrays sitting in committed collections, and can say what a stale populated array costs you in review and in secret hygiene.

for a principal

Weigh the open key/value attribute list against a closed per-scheme schema: extensibility and stable diffs on one side, no validation of parameter names on the other.

## The shape: one selector, one same-named array The collection format defines `auth` as a plain JSON object whose **only required member is `type`**. `type` is a string, and its value does two jobs at once: it names the scheme in force, and it names the key under which that scheme's settings are stored *in the very same object*. A basic-credential block therefore reads `{"type": "basic", "basic": [ ... ]}` — the word `basic` appears twice, once as a value and once as a key. Every credentialed scheme the format declares follows that pattern. `apikey` pairs with an `apikey` array, `hawk` with a `hawk` array, `oauth2` with an `oauth2` array, `ntlm` with an `ntlm` array. The one exception is `noauth`, which the format declares as an empty schema — anything is permitted under it, and in practice nothing is stored. ## What lives inside a scheme array Each element of a scheme array is an **auth attribute**, which the format defines as its own object, separate from the auth object above it. Its members are: - **`key`** — a string, and the *only* required member. This is the parameter name a handler will ask for: `username`, `password`, `token`, `in`, `realm`. - **`value`** — declared with **no type at all**, so any JSON value is legal there: a string, a number, a boolean, even an object. - **`type`** — an optional string. This is the *attribute's* own `type`, one level down from the auth object's selector; the two are unrelated and confusing them is a common reading error. Because the settings are a **list of named pairs** rather than a fixed set of declared fields, the format never has to know which parameters a given scheme needs. Adding a parameter to a scheme adds a row to its array; it does not change the schema. That is why an `apikey` block stores `key`, `value` and `in` as three sibling attributes rather than as three declared properties. ## Several schemes can sit in one object Nothing in the format restricts an auth object to a single scheme's array. It may carry several, all populated, with `type` naming exactly one of them. That is not an accident of the shape — the SDK's own documentation for `RequestAuth` shows an object holding both a `basic` array and a `digest` array with `digest` selected, and switching between them with `auth.use('basic')`. | Part of the object | What it is | Required by the format? | |---|---|---| | `type` | string naming the selected scheme | **yes** | | `basic`, `digest`, `apikey`, … | array of auth attributes for that scheme | no | | an attribute's `key` | the parameter name a handler reads | **yes** | | an attribute's `value` | the parameter value, any JSON type | no | | an attribute's `type` | an optional string on the attribute itself | no | ## How the SDK reads it The SDK models the object as a `RequestAuth` property. Its `parameters()` method returns `this[this.type]` — literally the array whose key equals the selector — so only the selected scheme's attributes ever reach a signing handler. `use(type, options)` sets the selector and lazily creates the matching parameter list; `update(options, type)` merges into one scheme's list without changing the selector; `clear(type)` empties a scheme's list and deletes it outright when it is not the selected one. On a request, `Request#authorizeUsing(type, options)` is the same operation one level up. ## Why the shape matters in practice - **Switching schemes is a one-word edit.** Changing `type` re-points the selector; the values you already entered for the other scheme stay where they are. - **Abandoned credentials linger.** A scheme array you stopped selecting is still in the document, still in version control, and still in any export. It is inert, not gone. - **Attributes diff cleanly but read poorly.** A list of `{key, value}` objects produces tidy line diffs, at the cost of being harder to skim than named fields. - **A missing `value` is legal.** Because only `key` is required, an attribute can validate perfectly and still leave a handler with nothing to sign with. - **The two `type` fields are different things.** One selects the scheme; one annotates a single attribute.

  • If an auth object carries both a `basic` array and a `digest` array, what happens to the one `type` does not name?
    Nothing signs from it. The SDK's `RequestAuth.parameters()` returns `this[this.type]`, so only the named array reaches a signing handler; the other stays in the document and survives serialisation untouched. Calling `auth.use('digest')` re-points the selector and makes the other array live without re-entering any of its values.
  • Which members of an auth attribute does the collection format actually require?
    Only `key`. The format's auth-attribute definition lists `key`, `value` and an optional `type`, and marks `key` alone as required. `value` is declared with no type at all, so it accepts any JSON value. An attribute carrying a key and nothing else validates fine, even though a handler reading it will find nothing to sign with.

saying these in an interview costs you the question

  • Says the settings are nested inside the type field as an object
  • Claims an auth object may hold only one scheme's parameters at a time
  • Thinks every auth attribute must carry a value; only key is required
  • Confuses an attribute's own type field with the auth object's selector
  • Assumes unselected scheme arrays are stripped when the file is saved