Developer journey
This is the red carpet from idea to a live App. Every step is paved for you — shared foundation, reference samples, AI skills, and automated review and promotion.
An App can be a custom automation (a form-driven workflow, a Factorial API job, a CSV/report export, an email notification, a scheduled task) or a marketplace integration (sync between Factorial and an external system, built on the integrations framework). The journey below is the same for both.
The journey has two phases: building the App and activating it for a customer.
For integrations, data flows in two directions:
- Inbound (Pull) — a scheduled process periodically fetches data from the external system and creates or updates records in Factorial.
- Outbound (Push) — a Factorial webhook fires when something happens in Factorial (e.g. a new employee is created) and the process pushes that data to the external system.
Both directions can live in the same App. Each direction is a separate process but business logic can be shared through modules.
Building the App
Section titled “Building the App”-
Request access — Developer. Fill the request-access form: contributor type and name, developer email, why you want to build on Factorial Code, and your Factorial contact. This is a one-time request to join the platform — not per App.
-
Get access approved — Factorial team. The team is notified and approves your request. Your development team is created and you receive an email to set up your account and sign in to the developer console.
-
Create an App — Developer. In the console, create a new App: its name, what it does, your language (JavaScript or Python), its type — a standard App or one built on the integrations framework, picking the data types it syncs — and the OAuth scopes it needs. For a framework App the scopes step opens with the scopes the framework and your data types need already selected. Scopes are optional — an App that doesn’t call the Factorial API needs no OAuth application, and you can add scopes later from the App’s OAuth tab. The App is provisioned automatically — no approval step — and a development workspace
dev-{app-id}is created, inheritingbase-app(andbase-integration-appfor integrations). Create as many Apps as you need this way. -
Clone the workspace locally — Developer.
Terminal window pnpm install -g @factorialco/fcode-clifcode clone dev-{app-id}Clone sets up the Factorial Code AI skills by default, so your coding assistant knows the platform from the first prompt (pass
--skipSkillsSetupto opt out). Base modules are available immediately:FactorialClient,fc-utils,checkWebhookChallenge,setupWebhook. -
Build the App — Developer. Use your favourite AI agent — the skills carry worked examples and references, and the samples show complete Apps. Point it at the relevant material too: the Factorial platform docs and, for integrations, the external system’s API docs or specs. Build on the published SDKs for all Factorial API access.
You can also build in the console itself. The assistant in the developer console knows this platform, can see your Apps, releases, demo companies and failing runs, and will take you from an idea to an implementation plan by asking what it needs to know. When a step needs code written, it hands the work to a coding agent running in your App’s workspace — only when you ask it to. Nothing it proposes happens until you approve it.
-
Test locally — Developer. Run any process on your machine with
fcode run {process-slug}— no deploy required. You may also build a test suite. -
Push to the cloud — Developer. Sync your local workspace up to
dev-{app-id}withfcode push. -
Test from Factorial — Developer. Exercise the App from a Factorial demo environment, where the OAuth token is provided out of the box — no credential handling in your code (see OAuth & API token).
-
Request a release — Developer. First gate the release: run the
fcode-code-validationskill on the dev workspace with your agent and don’t request while its report has Blockers. If you work with the CLI, push your changes first. The requested version is published as a workspace version ondev-{app-id}(every process and module snapshotted under that tag), copied toprod-{app-id}and published there under the same tag. The dialog shows what will be copied and which variables are missing in production; variables are never copied, so set those inprod-{app-id}by hand. From a terminal,fcode app:releases:request {version}in the App folder shows the same summary and requests the release (see the CLI). -
Mark deployed — Factorial team, or a Factorial admin of your development team. A Factorial team admin or an operator marks the release deployed, which points the
stablealias at the version and publishes the App. Your App is now live for customers — and listed on the Factorial Marketplace. 🎉 Who may do this is a matter of roles: see Roles & permissions.
Activating it for a customer
Section titled “Activating it for a customer”- Request the integration — Customer / Factorial admin. Submit an install form with the
customer_idand the integrations to activate. - Workspace provisioned — Platform, automatic. A
deploy-{installation-id}workspace is created. Repeatable — add integrations anytime. - Configure the integration — Customer / Factorial admin. Run the
{vendor}-setupprocess and provide the credentials or configurations the app may need. On submit, this will be saved, and Factorial webhook subscriptions or schedules are created. - Integration is live — Platform, ongoing. Inbound data flows in via the scheduled poll process; outbound events flow out via the webhook-triggered push process.