# Authentication: OAuth 2.1, registration and tokens

Source: https://neatlisting.com/docs/authentication

> How MCP clients sign in to NeatListing: OAuth discovery endpoints, dynamic client registration, client ID metadata documents, PKCE, scopes, redirect URIs, token lifetimes, refresh and revocation.

[Docs](https://neatlisting.com/docs) · Authentication

NeatListing runs its own OAuth 2.1 authorization server, following the MCP authorization spec. A client discovers it from the `401` on `/mcp`, registers itself, sends the owner to sign in with PKCE (S256), and gets a one-hour access token plus a 90-day rotating refresh token. The owner signs in with Google, picks locations and clicks Allow. Agents never see Google credentials.

## The flow

1. The client calls `/mcp` with no token and gets `401` with a `WWW-Authenticate` header.
2. It reads the protected resource metadata, then the authorization server metadata.
3. It registers at `/oauth/register`, or uses an https client ID that points at its own metadata document.
4. It opens `/oauth/authorize` in the owner's browser with a PKCE challenge.
5. The owner signs in with Google, picks locations and clicks Allow. The browser returns to the client's redirect URI with a code.
6. The client swaps the code at `/oauth/token` and calls `/mcp` with `Authorization: Bearer …`.

This is what the first step returns:

```
HTTP/2 401
content-type: application/json
www-authenticate: Bearer resource_metadata="https://app.neatlisting.com/.well-known/oauth-protected-resource/mcp", scope="listings.read listings.write"
```

## Discovery endpoints

All on `https://app.neatlisting.com`, which is also the issuer.

- `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-protected-resource`: protected resource metadata (RFC 9728). The resource is `https://app.neatlisting.com/mcp`.
- `/.well-known/oauth-authorization-server`, `/.well-known/oauth-authorization-server/mcp` and `/.well-known/openid-configuration`: the same authorization server metadata (RFC 8414) at each path, for clients that look in different places. NeatListing doesn't issue ID tokens.

The metadata lists `authorization_endpoint` `/oauth/authorize`, `token_endpoint` `/oauth/token`, `registration_endpoint` `/oauth/register` and `revocation_endpoint` `/oauth/revoke`. It also says `code_challenge_methods_supported: ["S256"]`, `client_id_metadata_document_supported: true`, grant types `authorization_code` and `refresh_token`, and token endpoint auth methods `none`, `client_secret_post` and `client_secret_basic`.

## Dynamic client registration

`POST /oauth/register` with a JSON body of client metadata (RFC 7591). No human is involved. A form-encoded body is accepted too.

```
POST https://app.neatlisting.com/oauth/register
content-type: application/json

{"client_name": "My agent", "redirect_uris": ["http://127.0.0.1:8976/callback"], "token_endpoint_auth_method": "none"}
```

- `redirect_uris`: 1 to 10, following the rules below.
- `token_endpoint_auth_method`: `none` (public client, the default), `client_secret_post` or `client_secret_basic`. Confidential clients get a `client_secret` once, in this response.
- `grant_types`, if sent, must include `authorization_code`.
- `client_name` is what the owner sees on the Allow page, up to 80 characters.

The response is `201` with a `client_id` starting `nlc_`. Registrations are rate limited per address; past the limit you get `429` with `slow_down`.

## Client ID metadata documents

Instead of registering, a client can use an https URL as its `client_id`. NeatListing fetches that URL and reads the client's metadata from it.

- The URL must be https with a path, and no port, credentials or fragment. Hosts that resolve to private addresses are refused.
- The document must be JSON whose `client_id` equals its own URL, with 1 to 10 valid `redirect_uris`.
- Only public clients: `token_endpoint_auth_method` must be `none` or left out.
- The fetch allows no redirects, 5 seconds and 20 kB. NeatListing caches the document for a day.

## Redirect URIs

- Any `https://` address.
- `http://` only on this machine: `localhost`, `127.0.0.1` or `[::1]`. A registered loopback address matches any port at sign-in, as long as the path and query match (RFC 8252).
- A native app's own scheme in reverse-domain style, like `com.example.app:/callback`, or one of the known MCP client schemes: `cursor:`, `vscode:`, `vscode-insiders:`, `windsurf:`, `zed:`, `claude:`.

Fragments and user info are refused. Other custom schemes are refused because many of them are operating system handlers.

## Authorization request

`GET /oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `code_challenge` and `code_challenge_method=S256`. PKCE is required for every client. `state` is passed back unchanged, along with `iss` (RFC 9207).

- `scope` is optional and defaults to both scopes.
- `resource` is optional. If sent, it must be `https://app.neatlisting.com/mcp` (or the issuer).
- A bad request is shown to the owner as an error page. It is not sent back to the redirect URI, since anyone can register a client and NeatListing shouldn't become an open redirector. If the owner clicks Deny, the client gets `error=access_denied`.

## Scopes

- `listings.read`: every read tool.
- `listings.write`: changes to listings, setup and waiting changes.

A client that asks only for `listings.read` gets a read-only connection. Its listing changes come back `blocked` with "This agent was connected read-only.", and setup and approval tools return an error saying the same.

## Tokens

`POST /oauth/token`, form-encoded.

- `grant_type=authorization_code` with `code`, `code_verifier`, `redirect_uri` and `client_id`. Codes last 10 minutes and work once.
- The response has `access_token` (starts `nla_`, 1 hour), `refresh_token` (starts `nlr_`, 90 days), `token_type: Bearer`, `expires_in` and `scope`.
- `grant_type=refresh_token` returns a new pair and retires the old refresh token. You can narrow the scope on refresh but not widen it.
- Reusing a refresh token after a newer one from the same chain was used ends the whole chain, and the client has to sign in again. Two copies of one app refreshing at the same moment (within a minute) are allowed. So is a retry when the tokens from the first refresh were never used, which covers a client that lost the response.
- Send tokens in the `Authorization` header. Query and body tokens aren't accepted.
- The token endpoint allows 120 requests a minute per address.

## Revocation

`POST /oauth/revoke` (RFC 7009) with `token` and the client's credentials. Revoking a refresh token ends its whole chain; revoking an access token ends only that token. The response is `200` whether or not the token existed, so it never reveals which tokens are real. A wrong client id or secret gets `401 invalid_client`.

## What the owner sees

1. If they aren't signed in to NeatListing, a page naming the app and a button to sign in with Google. Google asks them to allow managing their Business Profiles.
2. A page that says the app wants to manage their Business Profiles, with a checkbox for each profile they own or manage and Select all. If they have exactly one profile it is ticked for them; otherwise Allow stays off until they tick at least one.
3. Allow or Deny, under a short Terms and Privacy notice. Reconnecting the same app shows its earlier choice and updates it.

If the Google account has no profiles yet, the owner can still click Connect anyway. The agent then gets profiles that account manages later, and `get_setup_status` tells it how to help them find the missing profile. For apps on the owner's computer (a loopback redirect), the page hands the code to the app in a small window and keeps the owner on NeatListing.

## Disconnecting

The owner can disconnect any agent from the NeatListing dashboard at [app.neatlisting.com/app](https://app.neatlisting.com/app). Its tokens stop working at once, and its next call gets `401` with "This connection was revoked by the owner." Deleting the NeatListing account in Settings also withdraws NeatListing's access in each connected Google account.

## Questions

### Do I need to register a client by hand?

No. Dynamic client registration and client ID metadata documents both work without anyone at NeatListing doing anything. A client that supports neither can't sign in yet; email hello@neatlisting.com.

### Does NeatListing accept API keys?

No. Agents connect through OAuth so the owner always sees and approves the connection.

### Which Google permission does the owner grant?

Sign-in with Google plus the `business.manage` scope, which Google needs for Business Profile APIs. NeatListing keeps the Google refresh token encrypted and never hands it to agents.

## More docs

- [NeatListing MCP server docs](https://neatlisting.com/docs)
- [Change statuses, history and undo](https://neatlisting.com/docs/change-statuses)
- [High-risk fields](https://neatlisting.com/docs/high-risk-fields)
- [Errors and what they mean](https://neatlisting.com/docs/errors)
- [Tool reference: every tool and its inputs](https://neatlisting.com/tools)
