PopCraft Docs

An integration connects an account of yours at another service to a PopCraft workspace. The account stays yours: PopCraft acts in it only when you publish or ask it to.

Integration	What it is for
GitHub	Code: push a site to a repository of yours.
Vercel	Hosting: deploy a site to a project of yours.
Neon	Database and sign-in: a site's forms and visitors' accounts in a Postgres database of yours.
Supabase	Database and sign-in: the same, in a Supabase project of yours, with Supabase Auth.

Connecting an account is the first step and is what this page covers. What PopCraft does with a connection is on that integration's own page.

Which one do I need?

Your design has…	Connect	Then, in the Publish dialog
A form whose answers should be kept (waitlist, contact, RSVP)	Neon or Supabase	Database → New … database
Sign-up, sign-in, pages only members see, lists that are each visitor's own	Neon or Supabase	The same: sign-in is turned on with the database
Code you want to keep, review or build on	GitHub	Also send to → New GitHub repository
Hosting of your own, at your own domain	Vercel	Also send to → New Vercel project
A storefront that sells	Vercel	Store → Deploy store, once the Ecommerce plugin has set its Shopify store

Neon and Supabase do the same job: pick the one you already use. With neither, Neon is the quicker to start (a new project is ready in seconds; a Supabase one takes a minute or two).

Connect an account

Connect your own accounts · 0:14

Description

Home, signed in. The avatar opens the account menu and Integrations is chosen. The dialog lists GitHub, Vercel, Neon and Supabase, each with what it is for. Connect is clicked on Neon, a token is pasted (shown as dots) and Connect checks it: the Neon account appears under Neon. The same is done for GitHub, and its account appears under GitHub.

Open your account menu (top right) → Integrations. Or press ⌘K (Ctrl K) and type integrations.
Find the service and click Connect.
Either authorize PopCraft on the service's own page, or paste a token:

Way	What happens
Connect (authorize)	A window opens on the service. You approve, the window closes, and the account is listed. Shown when the service's sign-in is set up for PopCraft.
Use a token	You make a token at the service (the dialog links to the page), paste it, and click Connect. PopCraft checks it with the service before keeping it.

The account appears under the service with its name there (a login, a team, an email).

Tokens, per service

Service	Where to make one	What it needs
GitHub	Settings → Developer settings → Personal access tokens	The `repo` scope, or a fine-grained token with Contents and Administration: read and write
Vercel	Account Settings → Tokens	Scoped to the team that should own the project
Neon	Account settings → API keys	A personal or organization API key
Supabase	Account → Access Tokens	A personal access token

A connection is an account, not a place

One account holds many things: a Neon account has several projects and databases, a Vercel account several teams and projects, a GitHub account many repositories. Connecting does not choose among them. Each file chooses the repository, project or database it uses when it is published, so two files can use the same connection and different databases.

You can connect more than one account at the same service (two GitHub accounts, say).

Use a connection: one click, or find one you have

In the Publish dialog, each section that uses an account (Database, Also send to) shows:

Control	What it does
New Neon database, New GitHub repository, …	One per connected account that can do it. Makes a new one named after the site, in your own space at the service (or the account last used), and uses it at once: a database is attached, a repository or project is sent the published version.
Connect Neon, Connect Supabase, …	For a service not connected yet (owners and admins). Connects it, then makes the new one, in the same click.
Or find one you have	One list of every database, repository or project in every connected account. Type a few letters of its name, pick it, and it is used.

A name that is taken gets -2, -3… A large account lists its first 60 places; type to find the rest by name.

Who can connect

Connections belong to the workspace: the team selected in the app, or your personal space when none is.
In a team, owners and admins connect and disconnect accounts. Everyone on the team sees which accounts are connected.
Nobody sees the credential again after it is saved, including the person who connected it.

Disconnect

Click the bin beside the account. PopCraft forgets the credential, and withdraws it at the service where the service allows it. A token you pasted stays valid at the service until you delete it there.

How the credential is kept

It is encrypted before it is stored, and decrypted only on PopCraft's servers at the moment it is used.
It is sent only to the service it belongs to.
No API endpoint, plugin or AI tool returns it.
Deleting your account deletes your personal workspace's connections.

The AI agent

The agent can see which accounts are connected and can recommend an integration for what your design needs: a database for a form whose answers should be kept, for example. Ask:

Does this site need a database?

What do I need to connect to put this on my own hosting?

It cannot connect an account. It opens the Integrations dialog and you connect it.

Tool	What it does
`list_integrations`	The integrations, what each can do, and which accounts are connected.
`open_integrations`	Opens the Integrations dialog.
`list_integration_resources`	What a connected account holds, one level at a time (organizations, projects, databases…).
`attach_database`	Give the site a database: `create: true` makes one named after the site. Asks first.
`set_site_sign_in`	Turn visitor sign-in on or off. Asks first.
`get_form_submissions`	What visitors sent through the site's forms.
`add_site_destination`	A repository or hosting project for the site: `create: true` makes one. Asks first.
`deploy_site`	Send a published version to a destination. Asks first.

Anything that makes something in your account, attaches it or sends to it asks you to approve first.

The API and the command line

A personal access token with the integrations:read scope can list a workspace's integrations and connected accounts. Credentials are never returned, and accounts cannot be connected through the API.

curl -H "Authorization: Bearer $POPCRAFT_TOKEN" https://popcraft.app/api/v1/workspaces/WORKSPACE_ID/integrations

popcraft run --ui integration.list --json

Every place the workspace's accounts hold, for one use (database, repo or deploy), as one list:

curl -H "Authorization: Bearer $POPCRAFT_TOKEN" "https://popcraft.app/api/v1/workspaces/WORKSPACE_ID/integrations/candidates?capability=database"

Each entry is a connectionId and a complete target, ready to send to the file's database or destinations endpoint. Or skip choosing: {"create": true} there makes a new one named after the site (see each integration's page). All endpoints are in the reference.

When something goes wrong

What you see	What to do
The browser blocked the window	Allow pop-ups for PopCraft, then click Connect again.
The window was closed before the account was connected	The service's page was closed early. Click Connect again and finish there.
The token is refused	Check it has what the table above says it needs, and that it has not expired.
This Supabase credential cannot reach any organization	The token's account has no organization: make one in Supabase first.
No Connect button, only Ask a workspace owner or admin	Only owners and admins connect accounts in a team.
A place you made is missing from the list	The list is kept for a minute: wait, or type its name.