The Jetpack Start API is an endpoint and sample code that gives hosting partners the ability to sign up / authenticate WPCOM users and obtain license keys and other information for Automattic products (Akismet, VaultPress, Jetpack). This allows a new WordPress.org installation to be pre-configured before the user ever logs in.
To the end-user, this just looks like a link: Click to get your “FREE JETPACK PREMIUM PLAN”, which prompts them to grant the hosting partner access to their account, and then redirects them back to the hosting partner’s control panel system (e.g. cPanel) so that the plan can be provisioned.
Jetpack Premium or Professional Plans
After the user grants the hosting partner access to their account, the user should end up with a Jetpack Premium or Professional plan. The only difference should be that the plan is provisioned for 100 years from the current date.
We do this so that the hosting partner doesn’t have to renew the subscription and so that the user doesn’t get renewal emails that might confuse them.
Jetpack Start v2
Jetpack Start v2 is a set of APIs and some code in Jetpack which are designed to accomplish the same things as Jetpack Start v1 but with more extensibility and dramatically lighter integration costs.
High Level Overview
The partner-provision.sh script in Jetpack accepts the partner_id and partner_secret (provided to hosting partner by Automattic), and a user ID and optional plan slug and wpcom_user_id.
The script fetches a temporary access token using the OAuth credentials and passes this and the other params into a Jetpack wp-cli command. The reason for this separation is to reduce the risk of rogue plugins stealing the client ID/secret.
The wp-CLI command (partner-provision) then attempts to register the site (if necessary) and invokes the Jetpack Start API, which returns success=true/false and (optionally) a next_url to send the user to.
Behind the scenes, partner-provision does a bunch of checks:
- does this site have an existing master user? If so:
- provision the plan to them immediately
- redirect them into wp-admin
- are we able to automatically connect this site to an existing wpcom user? if so:
- generate an access token for that
- try to install the products in 30 seconds after the script returns
- return the access_token with the API response so the master user can be set up in Jetpack
- otherwise, set up a “deferred bundle” which will be provisioned as soon as a user connects, and return the authorize URL for the site. This will take the user through the regular Jetpack Connect flow and back to their site.
When the command finishes, it returns some JSON output like this:
{"success":true,"next_url":"https:\/\/jetpack.wordpress.com\/jetpack.authorize\/1\/etc"}
This can be decoded by the partner and used to email the user the next steps or send their browser directly to the next_url. If there’s an error, then the JSON will contain error_code and error_message fields.
Where possible (and by default) the partner provision command enables SSO and redirects the user via the SSO login link, resulting in passwordless entry into the site. This behavior can be disabled via the jetpack_start_enable_sso filter.
The v2 API also includes the ability of “reseller” keys to access the jpphp/partner-keys/new API, which lets them create new keys. This allows hosting partner marketplaces to offer Jetpack plans in bundles of, say, 100 Premium plans for distribution to their customers, typically Web Professionals or small hosting companies who then resell the plans to customers.
Integration process
- Obtain a Jetpack Partner ID and token
- Whenever your customer requests their Jetpack plan, run this script inside the site directory:
./wp-content/plugins/jetpack/bin/partner-provision.sh --partner_id={partner_id} --partner_secret={partner_secret} --user_id={wordpress_user_id} --plan={plan_slug} - If you have a allowlisted WordPress.com account to auto-connect the user to, supply the –wpcom_user_id={the_id} argument.
- The script makes a call to our servers to register the site (if necessary) and provision the requested plan and any additional plugins
- If the script is successful, it will exit with code 0, and a JSON string. If any next steps are required in the browser, the JSON will include a URL to send your user to. E.g.
{ success: true, next_url: "http://jetpack.wordpress.com/?foo=bar" } - If the script is unsuccessful, it will exit with code 1, and some text describing the error, like this:
{ success: false, error_code: "site_inaccessible", error_message: "We couldn't contact your site" } - Any additional products and settings will be installed on the site within a couple of minutes.
Integration process for plan resellers
As a Jetpack Partner, you can sell your customers “bundles” of Jetpack plans. The way this works is that you have access to an API to create new “partner keys”, which you generate for each “bundle”, and distribute to your customers, much like bulk license keys for other products like Microsoft Windows.
Those customers (e.g. hosts or web professionals) then use those keys to provision plans to their WordPress users.
These generated partner keys can have limits – certain numbers of premium or professional plans. You (the reseller) are responsible for paying Automattic for any plans generated using these keys, and in turn, you can bill your customers.
When your customers buy a bundle of Jetpack plans, you create a new key by generating a “client_credentials”-granted OAuth token, and then using that token to authenticate a request to the jpphp/partner-keys/new API, like this (assumes you have curl and the excellent JSON-parsing command jq installed):
# generate token PARTNER_ID= your partner id PARTNER_SECRET= your partner secret API_HOST=public-api.wordpress.com ACCESS_TOKEN_JSON=$(curl https://$API_HOST/oauth2/token \ --silent \ -d "grant_type=client_credentials&client_id=$PARTNER_ID&client_secret=$PARTNER_SECRET&scope=jetpack-partner") ACCESS_TOKEN=$(echo $ACCESS_TOKEN_JSON | jq -r ".access_token") # generate partner key PARTNER_KEY_INFO=$(curl https://$API_HOST/rest/v1.3/jpphp/partner-keys/new \ --silent \ --header "authorization: Bearer $ACCESS_TOKEN" \ -d "name=My%sKey&allowed_premium_plans=100")
After running the script above, PARTNER_KEY_INFO should contain a value like this:
{"id": 10, "name":"My%sKey","allowed_personal_plans":"0","allowed_premium_plans":"100","allowed_professional_plans":"0","notes":null,"client_id":"12345","client_secret":"ab34fd21,,,"}
The client_id and client_secret values are the ones you should or your customers should use to license Jetpack plans with the partner-provision.sh script.
Summary
Jetpack Start v2 dramatically reduces the upfront development investment from you the partnered host. Once you’ve obtained your keys from Jetpack Partner ID and token you can start integrating and provisioning plans.
As a part of our partnership agreement Jetpack is to be included in all new WordPress instances created on your system. This also completes the primary requirement for Jetpack Start v2 which is to have Jetpack the plugin available in the site wp-content/plugins folder.
Once you have sold a Jetpack plan or you’ve included a Jetpack Plan with your hosting plan all you need to do is run the single WP CLI script mentioned above to initiate auto-provisioning of the Jetpack plan.
