BUILD WITH SHAREAI
Build an appointment app that connects customers to ShareAI, prepares useful AI agendas and puts them in control of their AI spending.
The experience you’ll build
JamZY · AppointmentsChoose an appointment. Connect ShareAI. Arrive with a plan.
YOUR IMPLEMENTATION
Three concrete deliverables: connect the customer, prepare their appointment, and make the integration ready to verify.
A customer selects their ShareAI account, approves your app and returns to JamZY.
Sign in, refresh the session and disconnect successfully.
Turn an appointment goal into an agenda and questions through a deliberate AI request.
Generate a draft; saving an appointment makes no AI call.
Explain optional AI fees and collect the platform checks your review submission needs.
Every included platform and requested scope has recorded checks.
TAKE IT INTO YOUR EDITOR
Copy the complete guide with the implementation goal, required inputs and acceptance checks. Keep code examples, tables and documentation links together.
Ready for your project, in the format you need.
Updated
You’ll build a connection your customers can understand: their ShareAI account, an optional AI preparation draft, and a clear path back to their appointment.
Where you’ll work Your finished example
Connect your application to ShareAI Builder, from enrollment to a tested integration ready for review. This walkthrough uses JamZY, a small Node.js appointment application, to show each step: register the app, configure its Web platform, connect a customer’s ShareAI account and send an authorized AI request. Apply the same steps to your own product.
| Capability | What the customer agrees to | What JamZY demonstrates |
|---|---|---|
| Login with ShareAI | An account connection and the identity information your app requests. | A private customer identity from authenticated User info. |
| Pay with ShareAI · AI usage | Using the customer’s selected personal or organization account for authorized inference. | An appointment preparation draft funded by that account’s eligible credits. |
| Builder markup | The additional AI usage fee in the accepted application contract. | Optional usage monetization, after approval and contract publication. |
| Product payments | A particular purchase presented in a separate ShareAI checkout. | An extension explained in the payment walkthrough. The appointment demo does not implement checkout. |
Have a ShareAI account, permission to use the personal or organization account that will own the app, a public HTTPS callback, a logo, and working privacy, terms and account-deletion pages. To run the example, use Node.js 22 or newer and an HTTPS address for your application.
Screenshots use example application details. ShareAI addresses in this guide are production addresses. Generate preparation makes a real AI request and can spend credits; selecting or saving a demo appointment does not. Verification checks are completed by your own successful integration tests.
You can distinguish account login, AI consumption, optional surcharge and a confirmed product purchase. Reading this guide does not require a paid request.
You’ll create the Builder identity that owns your application and its customer relationships.
Where you’ll work Console → Builder Program
Builder Program opens for the intended owner and offers New app. An enrollment decision, application review, public information review and Monetization Gateway approval are separate steps.
You’ll give JamZY its own application record, so its identity, access and commercial terms stay together.
Where you’ll work Builder Program → Product → New app
Use a reachable public website for the application profile. A private or local-only website can fail validation even when your development callback is registered correctly. The new application starts as a draft. You can continue editing without making it public. Its application identifier is different from an OAuth client ID or a subscription ID.
JamZY appears under Product for the intended owner. Do not create an extra application for every device platform.
You’ll get OAuth options that fit where your app runs and who controls its credentials.
Where you’ll work New app → Application setup
For a JamZY deployment you operate yourself, choose the pricing model that matches your offering, SaaS, Vendor-hosted cloud app, The customer pays for their own consumption, and ShareAI for AI requests. These are example answers, not a requirement for every product.
| Where the app runs | OAuth choice | Where credentials live |
|---|---|---|
| Your hosted backend | Web server client may use a client secret. PKCE still applies. | The secret and tokens stay on your server. |
| Browser application / SPA | Public Web client with PKCE. | No embedded client secret. Use an appropriate browser or backend session design. |
| Self-hosted or hybrid distribution | Public client with PKCE under the onboarding policy. | Do not distribute a shared vendor secret to customer installations. |
| Windows, macOS, Linux, Android or iOS | One public client for each enabled platform. | PKCE and platform-appropriate secure storage; no bundled secret. |
The downloadable JamZY sample deliberately uses a public Web client with PKCE, even though it has a small backend. The server keeps tokens out of browser storage. A vendor-hosted answer permits a server client; it does not force you to choose one.
You can revisit the saved answers under Application Information → Application setup. Deployment changes can remove incompatible client secrets and require repeat verification. Review that impact before saving.
The saved deployment describes your real architecture. The client-secret option follows that answer; a disabled option is an explanation of the policy, not a missing credential.
You’ll give customers the product details and policies they need before they decide to connect.
Where you’ll work Application Information
Open Application Information after Dashboard. Work through the dedicated sections: details, application setup, presentation, branding, gallery and review. Give the product a useful description, an accurate website and clear screenshots of the customer workflow.
Use your own app identity. ShareAI branding belongs on the integration button and explanatory material; it should not replace your product logo. Keep privacy, terms and deletion links reachable without signing in.
Save changes when the floating save action appears. The public information proposal has its own review; editing an approved proposal does not silently replace the live public presentation.
A visitor can understand what JamZY does, who operates it, and how to request deletion. Public details and callback configuration refer to the same product.
You’ll ask for the access your appointment experience actually uses and make its billing purpose clear.
Where you’ll work Application → Use Cases
In Use Cases, enable Login with ShareAI for account connection and Pay with ShareAI for the customer-funded flow you intend to support. Request Monetization Gateway access only if your product will earn an additional fee on AI usage. Follow the approval status shown in Console.
| Scope | Why you would request it |
|---|---|
openid | Connect an account using its client-scoped identity. |
profile / email | Request profile or email claims only if your product needs them. |
inference | Call supported AI inference endpoints when permitted by the application configuration. |
monetization_gateway | Use the AI billing agreement accepted by the customer for surcharged inference. |
payments | Create and inspect customer payment requests. Each purchase still needs confirmation. |
JamZY requests openid profile inference monetization_gateway. It does not request payments and does not sell a product through checkout. Enabling a capability in Console does not grant it to an existing access token: the customer must authorize the scopes and terms.
The capabilities, configured scopes and authorization request agree. Avoid requesting optional access that your app never uses or cannot verify.
You’ll create one Web client for the browser-based JamZY experience, with the right authentication method.
Where you’ll work OAuth settings → Web
Different platforms have different credentials and callback rules. They are not separate products: subscriptions and customer management are aggregated for the application. Application testers are shared across platforms, with a maximum of five places including pending invitations; the owner does not consume a tester place.
Exactly one Web platform exists. Native platforms you have not configured do not block your launch.
You’ll return customers to your application after authorization, using an exact callback you own.
Where you’ll work Web → Configuration
In Web → Configuration, register the exact HTTPS callback your application handles. This guide uses https://jamzy.example/oauth/callback as an example. Replace jamzy.example with the HTTPS domain where you deploy your copy of JamZY, and use that same callback in your application configuration.
Provide the consent-screen name, terms, privacy and deletion information. Enable only the scopes you need, then save. Scheme, host, path and applicable query details must match the authorization request and code exchange. Do not use a wildcard or a URL fragment.
| Platform | Callback to implement |
|---|---|
| Web | Exact HTTPS address on your application. |
| Android | A reverse-domain app scheme matching the application ID, or a verified HTTPS App Link with the package and SHA-256 signing fingerprint. |
| iOS | A matching app scheme, or a verified HTTPS Universal Link with bundle ID and Apple App ID prefix. |
| Windows / macOS / Linux | A permitted exact HTTPS callback, a matching reverse-domain application scheme, or a supported loopback redirect on 127.0.0.1 / [::1]. The loopback port can vary. |
Installed apps authorize in the system browser and return through the registered callback. For claimed HTTPS app links, publish the required association file and run the association verification in Console. A callback that looks plausible in a form is not proof that your installed app receives it.
Opening the callback through the authorization flow returns to your app. A random code or mismatched state is rejected.
You’ll have the appointment interface and its ShareAI connection running with your own application identifiers.
Where you’ll work Your application → Environment configuration
JamZY is an appointment application with an optional AI preparation assistant. Its scheduler is a browser-only demonstration: there is no calendar provider, email delivery or appointment payment. The ShareAI authorization and AI API integration use the real configured upstream.
Download the JamZY reference source. It contains the Node server, browser UI, tests and a setup README; no certificates, secrets, dependencies or sessions. Review the files before running them. Put the Node process behind an HTTPS reverse proxy that preserves the public origin.
# .env — replace both identifiers with YOUR registered application.
JAMZY_PUBLIC_ORIGIN=https://jamzy.example
SHAREAI_CLIENT_ID=YOUR_WEB_CLIENT_ID
SHAREAI_APP_ID=YOUR_APPLICATION_UUID
SHAREAI_AUTH_ORIGIN=https://auth.shareai.now
SHAREAI_API_BASE_URL=https://api.shareai.now/api/v1
SHAREAI_SCOPES="openid profile inference monetization_gateway"
PORT=3443
BIND_HOST=127.0.0.1# Node 22+, behind your HTTPS reverse proxy
node --env-file=.env server.mjs
# Mocked upstream tests; these do not spend credits
node --test test/server.test.mjsCreate your application at console.shareai.now. Use its production client ID with https://auth.shareai.now and https://api.shareai.now/api/v1. The jamzy.example address is a placeholder for your app, not a hosted demo. Serve your own app over HTTPS so its Secure session cookie works.
JamZY also offers an API-key connection for comparison. This walkthrough uses the wallet/OAuth button. An API key does not establish the customer’s JamZY OAuth agreement and is not a replacement for the customer authorization flow.
The app loads through HTTPS. Its public origin, registered callback and client ID match your registration. No token or secret appears in page source or localStorage.
You’ll let a customer choose their ShareAI account and approve the access your app needs.
Where you’ll work JamZY → Pay with your ShareAI Wallet
From JamZY, select Pay with your ShareAI Wallet. The app opens the ShareAI authorization page. The customer signs in, selects a personal or organization account, checks the app and requested access, and accepts the applicable subscription terms.
const verifier = randomBytes(32).toString('base64url');
const state = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const authorize = new URL('https://auth.shareai.now/oauth/authorize');
authorize.search = new URLSearchParams({
client_id: clientId, response_type: 'code', redirect_uri: callback,
scope: 'openid profile inference monetization_gateway', state,
code_challenge: challenge, code_challenge_method: 'S256',
}).toString();
// Save state + verifier in the server session BEFORE redirecting.
// The downloadable server implements state expiry and one-time consumption.Key the local customer record by the authenticated, client-scoped sub and its issuer/client context. Personal and organization authorizations can select different paying accounts. A customer ID is not a global user ID, email address or internal organization database ID. Do not merge identities across platforms by matching display names.
Cancel, mismatched state, replayed code and expired authorization fail safely. The normal flow returns an authenticated account without exposing its tokens.
You’ll keep authorized requests working as tokens expire, while giving the customer a reliable way to disconnect.
Where you’ll work Your application → Session and token handling
| Credential | Purpose | How to handle it |
|---|---|---|
| Authorization code | One-time handoff from the authorization page. | Exchange once, using the matching verifier and callback. It is not an API token. |
| Access token | Authorizes API calls within the accepted grant and scopes. | Send as Authorization: Bearer …. Respect expiry and endpoint authorization errors. |
| Refresh token | Obtains replacement access tokens without another sign-in while the grant remains valid. | Store securely. Serialize refresh operations and atomically replace rotated credentials. |
| ID token | An OpenID Connect identity assertion for the client. | If you use it, validate signature, issuer, audience, expiry and nonce as applicable. Do not use it as an inference Bearer token. |
| Client secret | Authenticates a permitted confidential server client. | Store on the server. It is different from all tokens and is never bundled in a public client. |
# Public client refresh; run on a trusted terminal with scoped test credentials.
curl --fail-with-body 'https://auth.shareai.now/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode "client_id=$SHAREAI_CLIENT_ID" \
--data-urlencode "refresh_token=$SHAREAI_REFRESH_TOKEN"Use the returned expires_in instead of inventing a lifetime. If refresh returns a replacement refresh token, persist it with the new access token as one update. Allow one refresh in flight per session so concurrent requests do not reuse a rotated token. An invalid or revoked refresh grant requires reconnection; do not loop indefinitely.
Refreshing cannot add a scope or silently accept a new Monetization Gateway contract. Send the customer through authorization again for new permissions or terms. JamZY stores credentials only in server memory for a maximum one-hour demo session, authenticates User info instead of trusting an unverified ID token, and uses a Secure, HttpOnly, SameSite cookie. A production service needs its own durable, protected session design.
On disconnect, revoke the refresh/access credentials where applicable and clear the application session. Clearing a browser cookie alone does not revoke a ShareAI grant or cancel a paid subscription. Avoid logging codes, tokens, secrets or personal prompt content.
Expiry triggers one controlled refresh; new tokens replace old ones. Disconnect clears the application session and reports any revocation failure.
You’ll turn an appointment goal into an agenda and useful questions, with an explicit customer-funded AI request.
Where you’ll work Available Models → JamZY → Come prepared
Open Available Models in the application. Select the models and providers your product will offer and save the configuration. If the catalog cannot be loaded, resolve the upstream availability error before proceeding; repeatedly changing OAuth clients will not repair it.
JamZY loads its catalog only after connection. Choose a permitted text model, enter a short appointment goal and select Generate preparation deliberately. The selected account needs eligible credits and any required accepted AI billing terms. Choosing a date, reviewing an appointment and saving it do not send an inference request.
curl --fail-with-body 'https://api.shareai.now/api/v1/chat/completions' \
-H "Authorization: Bearer $SHAREAI_ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"model":"YOUR_ENABLED_MODEL_SLUG","messages":[{"role":"user","content":"Create a short agenda and three questions for a 15-minute appointment about planning a booking app."}],"stream":false,"max_tokens":192}'A real scheduling product needs a server-side booking store, availability checks, time-zone handling, cancellation policy and calendar or notification integration. These are separate from ShareAI authorization. Keep AI output as a proposal; validate any future booking action through your own application rules.
Use a model slug returned by the permitted catalog. Handle the actual response contract: JamZY supports ShareAI’s native message.content envelope and OpenAI-style choices[0].message.content. HTTP 200 with an incomplete or nested error response is not a successful reply.
On a spending-limit or insufficient-credit response, show a useful explanation and the supplied customer billing link. Preserve the selected account. Do not bypass its limit, switch payer silently or retry a charged operation in a loop.
Generate preparation returns a usable agenda and questions. The request is attributed to the authorized customer and application, with the selected model and accepted terms. The AI draft cannot book or change an appointment.
You’ll explain your additional AI fee in a subscription offer and publish the terms customers can accept.
Where you’ll work Application → Subscriptions
Request Monetization Gateway access through the app’s Use Cases if it is not already approved by the applicable administrative policy. Complete the questionnaire and follow its status. Approval enables configuration; customer permission and billing consent remain separate.
Example only: a 20% Builder markup on €1.00 of eligible network cost adds €0.20. At Standard pricing, ShareAI’s 5% fee applies only to that €0.20 markup, before any billable Event Ingestion. Use the live estimator and accepted contract for the actual calculation. A subscription offer in this flow is an AI billing agreement; account connection alone does not debit a fixed recurring price.
The ShareAI consent screen is authoritative for accepted terms. JamZY’s public client cannot infer the accepted billing plan from User info, so its connection panel does not claim an active subscription or invent a price for the appointment.
The offer explains the fee; the contract can be accepted by the customer. You understand which customers remain on older terms and why.
You’ll collect the real endpoint and scope checks needed to submit your application for review.
Where you’ll work OAuth settings → Testers and Verification
Open OAuth settings → Testers and invite up to five application-wide testers. Pending invitations consume a place but do not grant access; the recipient must accept. Owner access and invited tester access are different from public production access.
For each platform you intend to publish, open Verification. Complete real successful calls for the required endpoints and every configured scope. Check discovery and signing keys; test authorize/callback, code exchange, refresh, authenticated User info and revocation. Confidential clients must also test applicable introspection. Native claimed HTTPS links need association verification.
A profile/email scope needs its actual returned claims; use a personal test account where email is required. The inference and monetization_gateway scopes need a completed authorized AI request. Payments need a successful scoped payment API call. A generic successful HTTP response, browser screenshot or manual checklist does not replace Console’s recorded checks.
You have three choices for an unfinished platform: finish and verify it, exclude it from publication so it remains owner/tester-only, or remove it. Do not include a platform with callbacks or scopes you have not exercised. Configuration changes can invalidate checks, so refresh the recorded status after your final changes.
Every included platform shows the required configuration, endpoint and scope checks as complete. The guide’s personal checklist is only a reading aid.
You’ll know what is ready for review, how publication works and where to follow customer access afterwards.
Where you’ll work Application → Dashboard
Try the whole flow again with an eligible customer after launch: connect, inspect the account and consent, generate a short appointment preparation draft, refresh safely, handle a billing failure, then disconnect. Verify the live user experience instead of assuming that a successful save proves it works.
Callback mismatch: compare the registered URL and both request values exactly. Unauthorized tester: confirm invitation acceptance and the selected account. Missing scope or contract: request only enabled access and reconnect to accept it. No models: inspect Available Models and provider restrictions. Refresh failure: clear the failed local session and reconnect. Review blocked: inspect the platform checks rather than creating another OAuth client.
The app works for the intended customer, recorded checks support its publication state, and the customer can control or revoke the authorization.
Select the personal or organization account that will own the program enrollment before applying. Organizations can submit an application before verification, but staff approval alone does not activate access. Complete organization email and company verification from the onboarding checklist in Console. An approved organization remains Pending verification until both checks are complete. Builder, Provider and Creator programs follow this rule.
View Monetization Gateway pricing · Explore ShareAI for Startups · Scopes and permissions
Your public Terms & Conditions, Privacy Policy and deletion instructions must match the application and remain reachable without sign-in. ShareAI program acceptance, Monetization Gateway approval, the customer’s OAuth permission and the accepted billing contract are separate decisions. Refresh cannot add permissions or accept new commercial terms.
The legacy surcharge scope remains accepted for existing integrations. New examples use monetization_gateway. Keep existing wire fields such as surcharge_bps and surcharge_percentage unchanged.
View Monetization Gateway pricing · Explore ShareAI for Startups · Scopes and permissions
Standard charges 5% of the Builder markup. For €2.00 of AI network cost and a 10% markup, the customer pays €2.20. ShareAI receives €0.01 of the €0.20 markup; the Builder has €0.19 before Event Ingestion.
The first 1,000 settled Production Monetization Gateway requests are free each calendar month (UTC), shared across the Builder account. Additional requests cost €0.04 per 1,000 before eligible discounts. One settled request creates one event.
Pay with ShareAI on its own, inference-only access, ordinary account API keys and Staging or testing traffic do not incur Monetization Gateway Event Ingestion.
ShareAI for Startups offers a shared monthly allowance for actual ShareAI fees on an approved application. The current Launch, Growth and Momentum tiers list €1,000, €5,000 and €10,000 per month. The same budget covers ShareAI’s percentage fee on Builder markup and billable Event Ingestion together. It is not a gross-markup allowance, a separate free-event quota or free AI inference. The account’s first 1,000 free events do not consume it.
Remaining Event Ingestion fees are paid from the request’s new Builder earnings, then available Builder AI earnings and unrestricted AI credits. Customer AI charges and product payments stay separate.
ShareAI can approve application-specific fees or fee support for a fixed period or until changed. Review the application’s current pricing and Special Programs in Console for its approved terms, validity and consumed allowance. A tier change or pricing override does not reset the application’s monthly usage.
Launch keeps Log in with ShareAI optional. Growth and Momentum require it; Momentum also requires the official ShareAI for Startups badge in the application footer. ShareAI checks the badge weekly. Confirmed attempts to bypass requirements can lead to demotion, removal from the Startup Program or withdrawal from the Marketplace under the accepted program terms.
Enterprise rates are configured by the ShareAI team for the Builder account after agreeing a personalized offer. The assigned percentage and event rate apply to future requests.
View Monetization Gateway pricing · Explore ShareAI for Startups · Scopes and permissions