Authentication

The server authenticates with OAuth 2.1 against your Potloc account — the same credentials, SSO included, that you use on the platform (Signing in covers those). There is no API key, and nothing to set up in advance: a client that follows the specs below configures itself from the server URL alone.

Discovery

Two metadata documents, both public:

Document	Spec	What it gives you
GET /.well-known/oauth-protected-resource	RFC 9728	Identifies the resource and names its authorization server.
GET /.well-known/oauth-authorization-server	RFC 8414	The endpoints, grants and PKCE methods below.

The same authorization-server document is also served from GET /.well-known/openid-configuration, for clients that look there first.

Endpoints

Parameter	Value
Issuer	https://mcp.potloc.com
Authorization endpoint	https://auth.potloc.com/oauth/authorize
Token endpoint	https://auth.potloc.com/oauth/token
Revocation endpoint	https://auth.potloc.com/oauth/revoke
Client registration endpoint	https://mcp.potloc.com/register
Response types	code
Grant types	authorization_code, refresh_token
PKCE	S256, plain
Client authentication	none
Scope	mcp_customer

Use S256 for PKCE; plain is advertised for compatibility only. Clients are public — they authenticate with none and are issued no secret.

The issuer is the MCP host rather than the sign-in host on purpose: RFC 8414 requires the issuer to match the host the document was fetched from, and a client that finds anything else there rejects the document.

Registration

Clients register themselves at POST /register (RFC 7591). No client secret is issued and nothing has to be set up on your side.

curl -sS https://mcp.potloc.com/register \
  -H "Content-Type: application/json" \
  -d '{
        "client_name": "My MCP Client",
        "redirect_uris": ["http://localhost:8765/callback"],
        "grant_types": ["authorization_code", "refresh_token"],
        "response_types": ["code"],
        "token_endpoint_auth_method": "none"
      }'

{
  "client_id": "…",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:8765/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp_customer"
}

Registering gives an app no access. Each person it asks on behalf of signs in to Potloc, sees the app’s name and where it will take them once they approve, and decides. An app that only borrowed a familiar name is told apart by that destination.

Registration is idempotent. A client that re-registers with the same name, redirect URIs and scope gets the same client_id back rather than a duplicate, so a client that does not persist its credentials can register on every connection without accumulating anything.

Tokens

• Access tokens last one hour. Your client refreshes them with the refresh_token grant, so a long working session stays connected without asking you to sign in again.
• Tokens carry the mcp_customer scope. A token minted for another Potloc service is a valid bearer token but is refused here with 403 and insufficient_scope.
• A token acts as you. It reaches exactly the surveys your Potloc permissions reach, and it loses that access the moment your permissions change — see Permissions and data scope.
• Revoke one from Connected apps on your Potloc profile (app.potloc.com/en/profile/authorization), which signs the client out immediately. Removing the connector in your client, or calling https://auth.potloc.com/oauth/revoke, does the same.

Sessions

There are none. The transport is Streamable HTTP in stateless mode: every request carries its own bearer token, and the server keeps nothing between requests. Nothing to open, keep alive, or resume after a network drop.

When a token is missing or expired

The server answers 401 with {"error": "unauthorized"} and a WWW-Authenticate header pointing at the protected-resource document:

WWW-Authenticate: Bearer resource_metadata="https://mcp.potloc.com/.well-known/oauth-protected-resource"

A compliant client reads that header, rediscovers the authorization server and re-runs the flow on its own. The full list of responses is in Rate limits and errors.