OpenAPI and OAuth
GET /contract/openapi.json describes three ways to sign in, under components.securitySchemes:
token: an HTTP bearer token (a personal or proposal token).oauth2: the authorization-code flow (with PKCE) and its refresh. Scopes are the ones inOAUTH_SCOPES(ro,rw); the document is built from that list, so it cannot drift.openid: OpenID Connect discovery, at/.well-known/openid-configuration. No operation requires it; it is for discovery only.
Every operation that needs a login lists token and oauth2; either one is enough. Each oauth2 requirement names one scope: ro on a GET, rw on anything else (rw reads too). A client asks for one scope, ro or rw: the forge grants a single scope, so ask for rw if the client will write.
A generated client signs in
- Send the person to
authorizationUrl(/oauth/authorize) withresponse_type=code, yourclient_id,redirect_uri,scope(roorrw),stateand a PKCEcode_challengeandcode_challenge_method=S256. - The person approves; the forge redirects back with
code. - POST
code,code_verifierandgrant_type=authorization_codetotokenUrl(/oauth/token). The answer holdsaccess_tokenand, when the grant has one,refresh_token. - Call the API with
Authorization: Bearer <access_token>.
Refresh
When the access token expires (a 401), POST grant_type=refresh_token and the refresh_token to refreshUrl. It is the same endpoint as tokenUrl. Keep the new refresh token the answer returns.