Connected apps & OAuth

A connected app acts for one Cru customer, with their permission: an AI assistant, a portfolio tool, anything a customer signs in to with their own Cru account. It gets a token through OAuth 2.1 — the customer approves it on Cru’s site — and every trade it prepares waits for the customer to confirm.

Your appconnected app

The customerin their browser

Cru sign-in/api/oauth

Cru API/api/v1 · /api/mcp

GET · no tokenGET401 · WWW-Authenticate401GET /.well-known/…metadataendpointsendpoints

1 / 5A call without a token gets 401, and WWW-Authenticate points to the metadata that names Cru’s authorization server.

What the server implements

The authorization code grant with PKCE for every client, refresh token rotation, dynamic client registration (RFC 7591), revocation (RFC 7009), server metadata (RFC 8414), protected resource metadata (RFC 9728), resource indicators (RFC 8707) and iss on the authorization response (RFC 9207). Tokens are opaque. There is no OpenID Connect, no introspection endpoint and no client credentials grant.

Each market is its own issuer

Every market hostname serves its own authorization server, and its issuer is that hostname: https://us.cruworldwine.com for the market selected above. Connect on the host whose market the customer trades in. The customer can let the app use their other Cru sites too, and the token then works on those hosts as well.

Discovery

A request without a token gets 401 and a WWW-Authenticate header that points at the protected resource metadata — which is how an MCP client finds its way in without being told anything but the URL.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="cru", resource_metadata="https://us.cruworldwine.com/.well-known/oauth-protected-resource/api/v1"

{
  "issuer": "https://us.cruworldwine.com",
  "authorization_endpoint": "https://us.cruworldwine.com/api/oauth/authorize",
  "token_endpoint": "https://us.cruworldwine.com/api/oauth/token",
  "registration_endpoint": "https://us.cruworldwine.com/api/oauth/register",
  "revocation_endpoint": "https://us.cruworldwine.com/api/oauth/revoke",
  "response_types_supported": [
    "code"
  ],
  "response_modes_supported": [
    "query"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_post",
    "client_secret_basic"
  ],
  "scopes_supported": [
    "meta:read",
    "market:read",
    "wines:read",
    "portfolio:read",
    "bids:read",
    "offers:read",
    "trades:read",
    "addresses:read",
    "bids:write",
    "offers:write",
    "orders:write",
    "addresses:write"
  ],
  "authorization_response_iss_parameter_supported": true
}

Register your app

Registration is open to anyone and grants nothing on its own: a customer still has to approve the app. POST /api/oauth/register with a JSON body:

curl -X POST https://us.cruworldwine.com/api/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Example Cellar Tracker",
    "redirect_uris": ["https://app.example.com/oauth/callback"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

The answer is 201 with a client_id (cru_oc_…) and, unless you chose none, a client_secret (cru_cs_…) that does not expire and is shown only this once.

Send the customer to approve it

https://us.cruworldwine.com/api/oauth/authorize
  ?response_type=code
  &client_id=cru_oc_YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &scope=meta%3Aread%20market%3Aread%20portfolio%3Aread%20bids%3Aread%20bids%3Awrite
  &code_challenge=YOUR_S256_CHALLENGE
  &code_challenge_method=S256
  &state=YOUR_STATE

What the customer sees

The customer signs in to their Cru account if they are not already, on that market’s site. The consent page names your app — by the client_name you registered, which Cru cannot verify — and the address it will return them to, and asks two things:

• What it can see and do. The permissions you asked for, in two groups. The read permissions start ticked; meta:read cannot be unticked. The trading permissions and addresses:write start unticked even when you asked for them, with the promise that each bid, sale, purchase or address is shown to the customer first and only happens when it is separately confirmed.
• Which Cru sites it can use. The current one always, others if they tick them.

The customer can only take permissions away from what you asked for, never add to it. If they decline — or allow with nothing ticked — you get error=access_denied. The page stays answerable for 15 minutes. An account on hold cannot connect apps at all.

The redirect back

On approval the customer is sent to your redirect_uri with code, state and iss. Check iss is the issuer you started with. The code is single use and lasts five minutes.

Exchange the code

curl -X POST https://us.cruworldwine.com/api/oauth/token \
  -u "$CRU_OAUTH_CLIENT_ID:$CRU_OAUTH_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=cru_ac_THE_CODE \
  -d code_verifier=YOUR_PKCE_VERIFIER \
  -d redirect_uri=https://app.example.com/oauth/callback

{
  "access_token": "cru_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "meta:read market:read portfolio:read bids:read bids:write",
  "refresh_token": "cru_rt_…"
}

Refresh

curl -X POST https://us.cruworldwine.com/api/oauth/token \
  -u "$CRU_OAUTH_CLIENT_ID:$CRU_OAUTH_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=cru_rt_THE_REFRESH_TOKEN

A refresh may narrow the scopes, never widen them. Use each refresh token once: presenting one that has already been used revokes the whole connection — every token issued since the customer approved — on the assumption that it was stolen. So does replaying an authorization code. If the customer’s account goes on hold, the next refresh ends the connection for good.

Disconnect

POST /api/oauth/revoke with token= and your client authentication ends the whole connection, whichever of the two tokens you send. It always answers 200 {}, so it cannot be used to test whether a token exists. Customers cannot yet disconnect an app from their Cru account themselves: they ask Cru, which can also suspend an app outright.

Calling the API with a token

The REST API and the MCP server accept the token on any market host the customer allowed. It acts as that customer, with the scopes they granted:

• Reads behave exactly as for a partner. GET /ping shows the app’s name, the scopes, the market you called and when the token expires.
• Writes are staged and answer 202; nothing happens until you confirm the code with the customer’s agreement. Writes & confirmations →
• An expired, revoked or wrong-resource token is AUTH_INVALID_CREDENTIALS / 401, with error="invalid_token" in WWW-Authenticate. A missing scope adds error="insufficient_scope" and the scope it needs.
• A host the customer did not allow is AUTH_STORE_NOT_ALLOWED; an account on hold, AUTH_ACCOUNT_ON_HOLD.

OAuth errors

The OAuth endpoints answer in OAuth’s own format, {"error", "error_description"}, not the API envelope. Before the client and redirect are known to be valid, the authorization page shows the customer an error instead of redirecting.