Developer & agent API

Everything needed to build against https://class.withwind.tw: register a client yourself, get a token, call the API. No sales call, no email, no waiting for an API key — see the redirect-URI rule below for what self-serve registration covers.

Get credentials

Clients are created by dynamic client registration (RFC 7591): POST your client metadata to https://class.withwind.tw/api/oauth/register and the response carries your client_id. The authorization server advertises the same endpoint as registration_endpoint in its metadata, which is the source of truth if anything here disagrees.

Registration is open to any client redirecting to a loopback address (http://127.0.0.1:PORT/...), which covers CLI tools, desktop apps and local agents. A fixed HTTPS callback needs a registered integration — registering one is refused with invalid_redirect_uri rather than failing later at https://class.withwind.tw/oauth/authorize, so contact support or see https://docs.loopwise.com before building a hosted web client.

Purpose	Endpoint
Client registration	`https://class.withwind.tw/api/oauth/register`
Authorization	`https://class.withwind.tw/oauth/authorize`
Token	`https://class.withwind.tw/api/oauth/token`
UserInfo	`https://class.withwind.tw/api/oauth/userinfo`
Revocation	`https://class.withwind.tw/api/oauth/revoke`

Authenticate

Authorization Code flow with PKCE (S256). Public clients use the none token-endpoint auth method, confidential clients client_secret_post.

1. Register a client:

curl -X POST https://class.withwind.tw/api/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"My agent","application_type":"native","redirect_uris":["http://127.0.0.1:41234/callback"],"token_endpoint_auth_method":"none"}'

2. Send the person to the authorization endpoint with your PKCE challenge:

https://class.withwind.tw/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid%20profile%20courses:read&code_challenge=CODE_CHALLENGE&code_challenge_method=S256&state=RANDOM

3. Exchange the returned code for tokens:

curl -X POST https://class.withwind.tw/api/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=AUTHORIZATION_CODE' \
  -d 'redirect_uri=YOUR_REDIRECT_URI' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'code_verifier=CODE_VERIFIER'

4. Call the API:

curl https://class.withwind.tw/api/oauth/userinfo \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Refresh with the refresh_token grant, and revoke at https://class.withwind.tw/api/oauth/revoke (RFC 7009). Errors follow RFC 6749 §5.2: a JSON body with error and error_description; an invalid token is 401 invalid_token and a token missing a scope is 403 insufficient_scope. The full walkthrough is at /auth.md.

Scopes

Scope	Grants
`openid`	OpenID Connect authentication
`profile`	Basic profile information
`email`	Email address
`courses:read`	Read access to courses
`courses:write`	Write access to courses
`students:read`	Read access to students
`students:write`	Write access to students
`members:read`	Read access to members
`members:write`	Write access to members
`analytics:read`	Read access to analytics
`curriculum:read`	Read access to curriculum
`curriculum:write`	Write access to curriculum
`orders:read`	Read access to orders
`school:read`	Read access to school
`school:write`	Write access to school
`appearance:read`	Read access to appearance
`appearance:write`	Write access to appearance
`events:read`	Read access to events
`events:write`	Write access to events
`membership_plans:read`	Read access to membership plans
`membership_plans:write`	Write access to membership plans
`coupons:read`	Read access to coupons
`coupons:write`	Write access to coupons
`posts:read`	Read access to posts
`posts:write`	Write access to posts
`subscriptions:read`	Read access to subscriptions
`subscriptions:write`	Write access to subscriptions
`digital_products:read`	Read access to digital products
`digital_products:write`	Write access to digital products
`comments:read`	Read access to comments
`lecturers:read`	Read access to lecturers
`lecturers:write`	Write access to lecturers
`storage:write`	Write access to storage
`forms:read`	Read access to forms
`pages:read`	Read access to pages
`pages:write`	Write access to pages
`account:read`	Read access to account
`account:write`	Write access to account

Machine-readable resources

/openapi.json — OpenAPI 3.0 specification for this origin
/auth.md — The authentication walkthrough above, as Markdown
/llms.txt — Index of this site’s content for AI agents
/pricing.md — What this site sells, as Markdown
/mcp — MCP server (Streamable HTTP) for anonymous catalog reads
/.well-known/oauth-protected-resource — Protected Resource Metadata (RFC 9728)
/.well-known/oauth-authorization-server — Authorization Server Metadata (RFC 8414)
/.well-known/openid-configuration — OpenID Connect discovery document

Platform-wide documentation lives at https://docs.loopwise.com. Everything above is specific to https://class.withwind.tw.