Docs / YouSpot API authentication

YouSpot API authentication

YouSpot is an OAuth 2.1 authorization server for agents: dynamic client registration, PKCE S256, refresh-token rotation. Members can also mint a long-lived API token by hand.

YouSpot issues its own OAuth 2.1 access tokens to agents. A token is always bound to one member: every tool call reads and writes that person's data and nobody else's.

Discovery

https://youspot.com/.well-known/oauth-protected-resource (RFC 9728) names the resource and its authorization server.
https://youspot.com/.well-known/oauth-authorization-server (RFC 8414) names the endpoints below.

What identity you can hold

POST https://youspot.com/agent/identity answers that directly. Send {"type":"anonymous"} and it lists the surfaces that need no credential at all. Send {"type":"service_auth"} with a bearer token and it names the member whose access you are holding, and whether the credential belongs to a person's AI client or to one of their cloud agents. No other identity type exists here: there is no client-credentials grant, because a token that belonged to no person would have nothing to read.

Endpoints

Endpoint	Purpose
`POST /agent/identity`	What identity you can hold, and who you are holding. No credential needed to ask.
`POST /oauth/register`	Dynamic client registration (RFC 7591). Open: registration alone grants nothing.
`GET /oauth/authorize`	Consent. A signed-out person is sent through Clerk first, then shown what the client is asking for.
`POST /oauth/token`	Authorization code exchange and refresh. Refresh tokens rotate on use.
`POST /oauth/revoke`	RFC 7009. Revoking either token kills the pair. 200 whether or not the token was live.

The flow

Register a client, or reuse one you already registered.
Send the member to /oauth/authorize with response_type=code, code_challenge_method=S256, a code_challenge, your redirect_uri, and scope=linkedin.
They sign in and approve. You get a code on your redirect URI.
Exchange the code at /oauth/token with your code_verifier.
Call /mcp with Authorization: Bearer <access_token>.

Scope

There is one scope, linkedin, and it covers the whole tool surface. Finer-grained scopes are not issued yet.

API tokens

A member who wants to script against their own account without running an OAuth flow can mint a named token on the MCP tab at https://youspot.com/user/integrations/mcp. Send it the same way, as Authorization: Bearer <token>.

curl -X POST https://youspot.com/mcp \
  -H "Authorization: Bearer $YOUSPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Errors

A missing or expired bearer gets 401 with a WWW-Authenticate: Bearer header naming the protected-resource metadata URL, so a client can rediscover where to authorize.
A token belonging to a different member never sees your data; there is no cross-account read.