Connected apps
A connected app is a separate application registered as an OAuth client on your SDK platform. Users sign in on the platform and decide whether to connect it; the app may be run by someone else.
On this pageRegister a connected app · Understand what users approve · Use the publish flow for deployments
Register an application
Open Admin → Connected apps. Enter the app name, its operator, and each exact HTTPS callback URL on a separate line. Wildcards and callback query strings are not supported. Enable individual publish approvals if the app builds and deploys projects. Enable private previews to run checkpoints before publishing. Existing clients have an Enable private previews button; users must connect again to consent to that permission.
Save the returned client ID and secret on the app's server. The SDK shows the secret once. The client secret authenticates that application; it does not grant access to users' accounts. Register a new client if you need replacement credentials, then disable the old one.
Disable and revoke access invalidates the client's grants, pending sign-ins, and publish approvals. Registration and disablement appear in the operator audit.
Local development permits exact HTTP callbacks on localhost when the platform's development authentication bypass is explicitly enabled. Production clients require HTTPS.
Connect and disconnect
The app sends users to the platform's authorization page, where the platform displays its registered name, operator, callback origin, and requested permission. Sign-in permits reading the user's ID and username. It does not provide an account token or project management access.
Users can disconnect applications at <platform API URL>/oauth/connections. Grants also expire after an hour and become invalid when their platform login session is revoked or their account is suspended. Applications must request a new sign-in when access expires.
Private previews
Sign-in can request scope=profile preview:deploy when the administrator has enabled it. After user consent, the app can build private previews without approval for each checkpoint. Production publishing still requires individual approval.
Use the granted bearer token to:
- POST
{ workspace: externalWorkspaceId }to/oauth/previews. The response contains a stableproject_idand previewurlfor that client, owner and workspace. - POST
{ project_id, checkpoint, artifact: prepared.artifact }to/oauth/preview-deployment-requests. Use itsaccess_tokenandapproval_idwith the same asset upload and deployment protocol as publishing. - Once deployment finishes, POST to
/oauth/previews/:id/launchand open the returned URL. Launch URLs expire after one minute and can be used once. Reload the preview's origin after opening it.
Each workspace has a separate preview origin and resources, with no production secrets. Previews support HTTP apps with isolated D1, KV, R2, AI and native Durable Objects. Authentication, external databases, email, schedules, queues and containers require production publishing. Viewing requires the current user grant; disconnecting or disabling the app denies subsequent requests. Preview writes must originate from that preview's own origin.
Account Access policies must allow requests to generated preview origins to reach the platform. A policy that blocks new Workers hostnames also blocks previews. The SDK still requires a valid preview grant when the hostname is reachable.
Each owner can have ten preview workspaces. Each workspace permits sixty builds per hour and shares the owner's platform resource and usage limits. Inactive previews expire after seven days and the platform removes their resources. Opening the workspace through /oauth/previews renews that expiry. Disabling preview permission expires its previews.
Approve a publish
The app builds first, then sends the user to the platform with the prepared artifact. The platform displays the project name, checkpoint label, resources, manifest, and artifact digest. The user must explicitly approve on the platform.
Approval permits one deployment to that user's chosen project. The SDK creates a missing project during approval; existing projects require ownership. The app receives a credential valid for up to fifteen minutes, restricted to that artifact's asset uploads, deployment, and receipt. Retries use the same receipt.
Published code can use that project's existing secrets and resources. Review the app operator and deployment details before approving code for an existing project. Migrations and resource changes in the approved manifest take effect during deployment.
Disabling the app or disconnecting its grant stops authorization for subsequent actions and is checked again before a queued deployment publishes. Disconnecting does not remove an app that has already been published; manage that project through the platform.
Build an OAuth client
Discover endpoints at /.well-known/oauth-authorization-server on the platform API origin. Use authorization code flow with scope=profile, a random state, and S256 PKCE. Authenticate token exchanges using HTTP Basic client authentication. Send access tokens as Bearer credentials to /oauth/userinfo; its response contains sub, preferred_username, and the consented scope.
For publishing, package the built app with prepareDeployArtifact. Then POST to /oauth/deployment-requests with the profile token:
{
redirect_uri: registeredCallback,
state: publishState,
code_challenge: publishChallenge,
code_challenge_method: 'S256',
slug: projectSlug,
checkpoint: checkpointLabel,
artifact: prepared.artifact
}Redirect the browser to the returned authorization_url. Exchange its code with the publish verifier and the same registered callback. The response includes project_id, approval_id, and a deploy:approve access token. This publish flow is an SDK extension; requesting that scope in an ordinary sign-in does not authorize deployment.
Use the token to request URLs from POST /projects/:id/deploy/upload-urls, upload the declared assets, and send the artifact to POST /projects/:id/deploy. Set x-void-deploy-idempotency-key to approval_id. Deployment uses the platform's managed deployment protocol and requires the platform deployment Queue. The credential cannot read secrets, mint project tokens, delete projects, or deploy different bytes.
Revoke identity grants with POST /oauth/revoke, authenticated as the client. No refresh token or OpenID Connect ID token is issued.
If the API is protected by Cloudflare Access, the application operator must also configure a service identity permitted by that Access application's policy. Server OAuth endpoints and approved deployment requests still validate their own client, grant, and project authority; browser consent requires the user's company identity.
