Lesson 18.318.3 Finding the door

In everyday life. A sign on a locked office door says "Visitors, please check in at reception, Building B." You do not guess where reception is, and you do not trust a stranger in the hallway who offers to take you there.

What you will learn. How an AI app finds the right place to sign in, with nobody setting it up and nothing guessed.

Why it matters. An app that guessed could send a person to a look-alike page that collects passwords.

One request, start to finish. Ana's app has just received the 401 from step 1 in 18.2. How does it know where Ana should sign in?

1. The 401 carries a link to a small document the connector publishes about itself, and the scopes (permissions) it needs.
2. The app fetches that document from the connector. It says: "I am the connector at this address. My tokens come from this sign-in server. These are the scopes I know."
3. The app fetches the sign-in server's own document, from a standard address under the sign-in server's own address. Standard addresses like these start with /.well-known/, so any program knows where to look. For example, if Brightline's sign-in server lives at https://auth.brightline.example/api/auth, its document lives at https://auth.brightline.example/.well-known/oauth-authorization-server/api/auth: the standard part goes in the middle, and the server's own path moves to the end. The document lists where to send the browser, where to swap a code for tokens, where to find the keys that check its tokens (18.6 explains them), and what the sign-in server supports.

Now the app knows everything it needs for steps 3 to 8 of 18.2, and nothing was guessed.

What is discovery?

Finding these documents is called discovery. Each metadata document is a small, public file in JSON (the text layout of labels and values from 17.1) that describes one server, so other programs can learn how to talk to it without being set up by hand.

Why two documents?

Because there are two servers, often run by different people. One document describes the connector: where its tokens come from. The other describes the sign-in server: how to sign in there. A company might run ten connectors that all trust one sign-in server.

The rules:

• The connector must publish its document, naming its sign-in server, and must say where the document is: by the link in the 401, at a standard address under its own, or both. Brightline does both. The app must try the link in the 401 first, and the standard address if there is no link.
• The sign-in server must publish its document. The app must be able to read it.¹

Why must the app not guess?

If an app took the sign-in server's address from anywhere other than the connector itself, such as a link in an email or a web page, an attacker could slip in the address of a look-alike sign-in page and collect passwords. The app follows links that start at the connector itself: the 401 points to the connector's document, and that document names the sign-in server. So the app sends Ana only where Brightline's connector says.

Which scopes does the app ask for?

The 401 should name the scopes the connector needs. The app asks for those first. They should be the minimum for ordinary use. More can be asked for later (18.7).

At work. The builder asks Claude Code to call the online connector with a small program that sends one web request and shows the reply, with no token, then to fetch the two documents that reply leads to. The builder reads each: the connector's names the Brightline sign-in server, and the sign-in server's lists its addresses and where its public keys are.

The operating rule: a connector that requires sign-in answers a request with no token with a 401 that points to its own document, and its document names its sign-in server. AI apps follow that chain, never a guess.

The standards behind this concept: protected resource metadata (RFC 9728)² for the connector's document, and authorization server metadata (RFC 8414)³ for the sign-in server's. Field guide F4 shows both documents and the 401's exact header.

Figure 18.6. From the first 401 to the sign-in server, by following links the connector publishes.