Skip to main content

Getting started

WPCS offers integrations using the API. This document will show how to call the API to create a new tenant in a certain product.

Create an API key​

Firstly, you'll need to create an API key and secret for your product. You can create API keys for products by clicking the API Keys button in the sidebar. You can read more about API keys here.

Now that you have your API key and secret, let's continue with making your first request.

Making requests​

Authentication​

Before we get to making your first requests, you'll have to make sure your request are authenticated. You can authenticate using Basic Auth. If you're not sure how HTTP request headers work, we recommend you use software like Postman to help things along. In a nutshell: in the Authorization section of Postman, choose Basic Auth and put your API key in the username field, and your API secret in the password field. You can read more about authenticating requests here.

Creating tenants​

The API root domain is https://api.eu1.wpcs.io or https://api.us1.wpcs.io (depending on the region your product resides in). In order to create a new tenant, you will make a POST request to https://api.eu1.wpcs.io/v1/tenants if you are in the EU1 region.

The body of the POST request needs to contain the following information:

  1. externalId: this is some identifier from your administrative system that you can use to target the tenant later. Setting this field with a known identifier is useful so you do not have to store the internal WPCS IDs when creating tenants via automations.
  2. name: the name of the tenant. This is the name you see in the console for tenants.

Optionally, you can also define the following:

  1. tenantName: the name of the tenant user. This should be a valid WordPress username. This may also be your customer's E-mail address.
  2. tenantEmail: the tenant WordPress user's E-mail address.
  3. tenantPassword: a specific password for the tenant to be created with. This is useful when you want to allow your customers to choose their password right away. If this value is omitted, a password is generated for the WordPress user. Your customer can then login via your own process, or click the Forgot password? link in the WordPress login screen.
  4. tenantUserRole: the WordPress role slug you want the tenant user to have. Do not use the role's display name here. Make sure that the role exists on the version you are creating the tenant on. If the role does not exist, the created user will not have any rights in WordPress. If the role is not provided the user will be assigned the configured WordPress default role. The default role can be configured in WordPress' settings.
  5. groupName of the tenant snapshot to base the tenant on: when you supply this field the latest snapshot from that group is used to base the tenant on. Make sure that there is a tenant snapshot with that group name in your production version.

A minimum POST request body could look like this:

JSON
{
    "externalId": "my-own-identifier",
    "name": "Client Company Inc",
}

However, using all the options, it could look like this:

JSON
{
    "externalId": "my-own-identifier",
    "name": "Client Company Inc",
    "tenantName": "John Doe", // optional
    "tenantEmail": "j.doe@example.com", // optional
    "tenantPassword": "averystrongpassword", // Optional
    "tenantUserRole": "store-owner", // Optional
    "groupName": "my-snapshot-group-name", // Optional
}

After making the request, you will receive a response with status code 201 Created. This means your tenant creation request has been received and is queued for tenant provisioning.

Configuring tenant domain names​

When you create a tenant in WPCS (via the console or the API), the tenant will be given a base domain name. You can read more about domains here. Via the API, you can immediately provide a domain name that will be used as the main domain as soon as it verifies.

You can provide this domain name via the POST request body:

JSON
{
    "externalId": "my-own-identifier",
    "name": "Client Company Inc",
    "tenantName": "John Doe",
    "tenantEmail": "j.doe@example.com",
    "customDomainName": "myexampledomain.com"
}

After the tenant has been created, the provided domain is also created and the verification process starts.

Providing branded temporary domains​

When your tenant does not have its main domain yet (maybe it hasn't been bought yet or it still points to an old site), you might want to give tenants a prettier temporary domain than the one generated by WPCS. Say you sell your product under the domain name my-awesome-product.com, it could make sense to give your customers a temporary domain name like acmeinc.my-awesome-product.com.

Setting this up starts at your DNS provider. You can create a CNAME record for *.my-awesome-product.com which points to public.eu1.wpcs.io.

Next, set up your API calls to provide a unique customDomainName. You might choose to use your tenant's company name for example. If your tenant signs up with the company name 'John Doe Inc', you can provide the domain name johndoeinc.my-awesome-product.com. Your whole POST request might look like this:

JSON
{
    "externalId": "11112222333334444",
    "name": "John Doe Inc",
    "tenantName": "John Doe",
    "tenantEmail": "j.doe@johndoeinc.com",
    "customDomainName": "johndoeinc.my-awesome-product.com"
}

Because your DNS has already been set up with a CNAME record, this custom domain name will verify very quickly. Now, you can communicate a branded URL to your tenants!

Production versions​

When a tenant is created using the API, it will be created under the version that has been set as Production. If you've updated your product in a next version, tenants created via the API will only be provisioned under that next version after you've set it as Production. Go to the version detail screen, hit Actions and then Set as production.