How theses work
Writing needs the user’s permission: the OAuth scope
thesis (“Post theses and replies, react and report in your name when you use the app”). Request it at sign-in together with the scopes you already use.
Reach
By default you see the theses of all platforms for a token. With the instance reach you see only the theses written on your instance: on all live apps of your registrable domain, or only on the app itself while it is in development or sandbox mode. Reach is the same on every plan.Two ways to integrate
Client-side apps that do not want a backend can also call the public browser API on id.cabalspy.xyz with your instance’s public client_id and the user’s access token.
Path 1: the widget
data-client-id the widget uses the design you saved for your instance, and theses written in it are attributed to your app.
data-client-id is required. It is your instance’s public client_id (Instance ID, csid_...), shown in the API Dashboard under CabalSpy ID, Instances next to the API key. It is not the API key and not a secret. If the attribute is missing, widget.js uses the client id of a data-csid-login button on the same page. The widget only loads on your instance’s sites: the allowed origins, the origins of your redirect URIs and your verified domain including subdomains, plus http://localhost:* and http://127.0.0.1:* while the instance is not live. The /embed/thesis iframe behind the widget may only be framed by these sites. See Client ID.Design in the dashboard
Design the widget in the API Dashboard: CabalSpy ID, Instances, your instance, tab Theses. The designer shows a live preview and the embed code, and saves:- Reach: all platforms or only this instance.
- Theme: dark or light, with the colours background, card, text, muted, border, accent, accent text, bull and bear.
- Font: system, inter, mono or serif.
- Corner radius: 0 to 24 px.
- Default sort: new or top.
- Show header, show the bull/bear filter, compact layout.
Attributes
Every attribute overrides the saved design for that one embed.
Invalid values fall back to the theme’s defaults.
Writing in the widget
The samewidget.js also renders the login button. How users write:
- Browser apps using the login button: request the scope, for example
data-scope="openid profile thesis"on the login button. After sign-in the widget hands the access token to every thesis widget on the page automatically. - Server apps or your own session: pass the user’s CabalSpy ID access token yourself. It must carry the scope
thesis.
Your own sign-in
Platforms with their own sign-in can take over the widget’s Sign in to write button withCSID.thesis.setSignInHandler(fn). When a handler is set, the button calls fn instead of the page’s login button or the popup. fn gets a token with the scope thesis for the person, for example your platform’s own CabalSpy ID access token fetched from your backend, passes it to CSID.thesis.setAccessToken(token) and resolves true. Resolving false means the person is not signed in.
cabalspy-id 0.5.2) the same is setThesisSignInHandler(fn) from cabalspy-id/widget, or the optional onSignIn prop on <CabalSpyTheses> in React.
Path 2: your own UI
Read with your API key, write from your backend in the name of a user. A typical Post thesis button works like this:1
Request the scope thesis at sign-in
Add
thesis to the scopes of your authorization request or the login button’s data-scope. Store the user’s sub, it is their csid_id.2
Check eligibility
Before you show the composer, ask whether the user can post on this token. Show the button only when
can_post is true, and a reply box when can_reply is true.3
Post from your backend
Your frontend sends the text to your backend, your backend posts it with your API key and the user’s The response is
csid_id. Never trust a csid_id sent by the browser, take it from your own session.201 with the new thesis, including the author’s position. Errors such as not_a_holder, invalid_body or rate_limited carry a message you can show the user.4
Render the list and go live
Load the token’s theses with GET /v1/theses (pass the viewer’s
csid_id to get my_reactions and is_mine) and the counts with GET /v1/theses/summary. Then open the theses stream and subscribe to the token to receive new posts, replies, reactions and removals:Endpoints
Reading is open to any API key, theses are public and not limited to your instance. Writing works only for your users: they signed in to your app with the scope
thesis, did not revoke it, are not blocked by you and are within your plan’s user limit. Sandbox test users cannot write.
