Docs · Authentication
Authentication: OAuth 2.1, registration and tokens
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
- The client calls
/mcpwith no token and gets401with aWWW-Authenticateheader. - It reads the protected resource metadata, then the authorization server metadata.
- It registers at
/oauth/register, or uses an https client ID that points at its own metadata document. - It opens
/oauth/authorizein the owner's browser with a PKCE challenge. - The owner signs in with Google, picks locations and clicks Allow. The browser returns to the client's redirect URI with a code.
- The client swaps the code at
/oauth/tokenand calls/mcpwithAuthorization: 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/mcpand/.well-known/oauth-protected-resource: protected resource metadata (RFC 9728). The resource ishttps://app.neatlisting.com/mcp./.well-known/oauth-authorization-server,/.well-known/oauth-authorization-server/mcpand/.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_postorclient_secret_basic. Confidential clients get aclient_secretonce, in this response.grant_types, if sent, must includeauthorization_code.client_nameis 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_idequals its own URL, with 1 to 10 validredirect_uris. - Only public clients:
token_endpoint_auth_methodmust benoneor 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.1or[::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).
scopeis optional and defaults to both scopes.resourceis optional. If sent, it must behttps://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_codewithcode,code_verifier,redirect_uriandclient_id. Codes last 10 minutes and work once.- The response has
access_token(startsnla_, 1 hour),refresh_token(startsnlr_, 90 days),token_type: Bearer,expires_inandscope. grant_type=refresh_tokenreturns 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
Authorizationheader. 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
- 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.
- 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.
- 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.