Docs · Authentication

Authentication: OAuth 2.1, registration and tokens

Updated 5 min readView as Markdown

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. 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 is free. Connect your Google Business Profile to Claude, ChatGPT or any app that supports MCP.