For Vepp admin

How to sell Vepp via API

To sell Vepp services automatically, implement the following operations: 

  • service creation — creates a Vepp (service) instance on the platform. The operation is run after a client has ordered the service; 
  • service suspension  — suspends a Vepp instance on the platform. The operation is run by a provider or when the payment period is over;  
  • service activation — activates a Vepp instance on the platform. The operation is run by a provider or when the payment is made;  
  • change of service parameters — changes the maximum number of websites in Vepp.  The operation is run after the value has been changed.
  • service deletion  — deletes a Vepp instance on the platform. How it will be deleted depends on how you sell Vepp: 
    • if Vepp is a stand-alone service  — deletes the instance when the client cancels the main service (server);  
    • if Vepp is a server add-on  — blocks the instance instead of deleting it. The client's license won't be used. If the client re-orders the service, the previous Vepp instance will be allocated; 
  • automatic login to Vepp — switches into the Vepp interface from a client area (the billing system). 

Creating a service


To create a Vepp instance on the platform: 

  1. Receive information about the client's server. 
  2. Set the account login on the platform.
  3. Make sure that the account exists.
  4. Create the account, if it doesn't exist.
  5. Create a Vepp instance for the account. 
  6. Wait when the operation is completed. 
  7. Save the information about the newly created instance. 

Receiving the server information

To create a Vepp instance, you need the information about the client's server: 

  • the server IP address;
  • the root password that will be used only for the first login. After that, the ssh-key will be used. 

Note.

If you offer Vepp as an add-on to VPS or dedicated server, you should start creating the instance only after the OS is installed and the ssh server is started. 

Selecting the user admin

We recommend using the client's email as a login to Vepp. If the client orders several services, use one account for all Vepp instances.

Checking that the user exists 

To check that the user exists, send a GET-request to the following URL https://domain.com/api/auth/v3/user_exist/{email}. The function doesn't require authentication. 

The following is the example of the request via curl: 

Check that the user exists
curl -X GET https://domain.com/api/auth/v3/user_exist/admin@example.com | jq

You will receive the JSON-object something like the following:

Response JSON
{
  "email_confirm": true,
  "exist": true,
  "last_notify": 1
}

Note.

If the user doesn't exist in Vepp, the JSON-object doesn't contain the parameter email_confirm

Checking access permissions

Create Vepp instances only for accounts with "User" access level. To check the level, send a GET-request to the following URL https://domain.com/api/auth/v3/user/{email}. The function is available to Vepp users and administrators. 

Note.

The user can get information only about his account.

The following is the example of the request via curl: 

Get information about the account client@example.com
curl -X GET 'https://domain.com/api/auth/v3/user/client@example.com' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' | jq

You will receive the JSON-object: 

Response in JSON
{
  "avatar": null,
  "avatar_content_type": null,
  "avatar_filename": null,
  "email": "client@example.com",
  "email_confirm": true,,
  "full_name": "example client",
  "id": 2,
  "lang": "ru",
  "password": "********",
  "phone_number": "+1 000 00-00-000",
  "property": null,
  "roles": [
    "@user"
  ],
  "ssh_pub_key": "ssh-rsa ...",
  "state": "active",
  "used_demo": false
}

Creating a user 

To create a platform user, send a POST-request to the following URL https://domain.com/api/auth/v3/user. The function is available to the platform administrators. 

The following is the example of the request via curl: 

Create a user
curl -X POST 'https://domain.com/api/auth/v3/user' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{"email": "client@example.com", "password": "password", "full_name": "example client", "phone_number": "+1 000 00-00-000", "lang": "ru", "terms_of_use": true, "privacy_policy": true, "mailing_policy": false, "no_need_mail": true}' | jq
 POST-request parameters

email (mandatory) — client's email and login in Vepp.

password (mandatory) — user password to access Vepp.

full_name — a full name of the client that will help identify him on the platform administrator form.

phone_number — client's phone number that will be displayed on the platform administrator form.

lang — client' interface language. Possible values: ru, en. If another value is sent, the English language will be applied. 

terms_of_use (mandatory) — terms of use. Possible values: 

  • true — the client accepts the terms of use; 
  • false — the client doesn't accept the terms of use. All API-request from his name will be canceled. 

privacy_policy (mandatory) — acceptance of the Privacy policy. Possible values: 

  • true — the client accepts the Privacy policy; 
  • false — the client doesn't accept the Privacy policy. All API-request from his name will be canceled. 

mailing_policy — accept notifications from Vepp. Possible values: 

  • true — the client wants to receive notifications from Vepp;
  • false — the client doesn't want to receive notifications from Vepp.

no_need_mail — disable notifications about new registration in Vepp to the user's email. Possible values: 

  • true — do not send notifications to the client's email; 
  • false — send notifications to the client's email; 

You will receive the JSON-object: 

Request in JSON
{
  "id": 2
}

Creating an instance 

To create a Vepp instance, send a POST-request to the URL like this https://domain.com/api/auth/v3/instance. The function is available only to the platform users. 

The following is the example of the request via curl: 

Create a Vepp instance
curl -X POST 'https://domain.com/api/auth/v3/instance' -H 'Cookie: ses6=E7CA54FA24C8AD4F71E0761A' -d '{"host": "0.0.0.0", "password": "password", "product": "vepp", "bill_id": "1"}' | jq
 POST-request paramaters

host (mandatory) — IP address of the client's server. 

login — username to access the server via ssh. 

password (mandatory) — password to access the server via ssh. If the login parameter is not specified, Vepp uses "root" as the login. 

port — port to access the server via ssh. If it is not specified, use port 22. 

product (mandatory) — instance type: "vepp".

bill_id (mandatory) — service id in the billing system for associating with the instance in Vepp. It is used in requests to change a service in the Vepp web interface. 

You will receive the JSON-object: 

Response in JSON
{
  "id": 1,
  "task_id": 1
}

Waiting when the creation operation is completed

To monitor an instance status you should request information about it at regular intervals.  The creation task is considered completed when the status parameter equals fail or active. 

To receive information about an instance, send a GET-request to the URL like the following: https://domain.com/api/auth/v3/instance/{id}. The function is available to Vepp administrators and users.  

The following is the example of the request via curl: 

Receive information about the instance with code 1
curl -X GET 'https://domain.com/api/auth/v3/instance/1' -H 'Cookie: ses6=E7CA54FA24C8AD4F71E0761A' | jq

You will receive the JSON-object: 

Response in JSON
{
  "demo": false,
  "expires_at": null,
  "failure_reason": {
    "code": 2201,
    "desc": "SSH connection by password failed",
    "details": "failed to connect to 0.0.0.0 reason'Connection refused'"
  },
  "host": null,
  "id": 1,
  "is_owner": true,
  "name": "vepp-1",
  "product": "vepp",
  "service_id": null,
  "service_info": null,
  "service_params": null,
  "service_status": null,
  "status": "fail",
  "sub_domain": "vepp-1.vepp.example.com"
}
 Response parameters

failure_reason — cause of the error of the Vepp instance initialization.

status — instance current status. 

sub_domain — web interface of the Vepp instance is available by this domain name. 

Saving data

Save the instance id and domain for accessing it.

Suspending a service 


To suspend a service without deleting it, send a POST-request to the following URL https://domain.com/api/auth/v3/instance/{id}/suspend. The function is available for the platform administrator. The Vepp instance will be suspended and protected from automatic activation.

The following is the example of the request via curl: 

Block the service with id 1
curl -X POST 'https://domain.com/api/auth/v3/instance/1/suspend' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{}' | jq
Response in JSON
{
  "id": 1
}

Activating a suspended service 


To activate a suspended service, send a POST-request to the following URL https://domain.com/api/auth/v3/instance/{id}/resume. The function is available to the platform administrator. The instance can be started automatically when someone is accessing it. 

The following is the example of the request via curl: 

Start the service with id 1
curl -X POST 'https://domain.com/api/auth/v3/instance/1/resume' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{}' | jq
Response in SON
{
  "id": 1
}

Changing service parameters


To change the maximum number of websites in Vepp, send a POST-request to the following URL  https://domain.com/api/auth/v3/instance/{id}/set_limits. The function is available to the platform administrator.

The following is the example of the request via curl: 

Change the website limit for service id 1
curl -X POST 'https://domain.com/api/auth/v3/instance/1/set_limits' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{"limits": {"site_limit": 10}}' | jq
 POST-request parameters

site_limit — the maximum number of websites. We recommend using a 5-fold value.

The response will contain the instance id and the id of the task to update Vepp instance license.

Response in JSON
{
  "id": 1,
  "task_id": 1
}

Deleting a service


To delete the Vepp instance, send a DELETE-request to the following URL https://domain.com/api/auth/v3/instance/{id}. The function is available to the platform administrator.

The following is the example of the request via curl:  

Delete instance with id 1
curl -X DELETE 'https://domain.com/api/auth/v3/instance/1' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' | jq

The response will contain the instance id and the id of the task to delete Vepp instance.

Response in JSON
{
  "id": 1,
  "task_id": 1
}

The deletion task is considered completed when the error "Instance not found" is returned or the status parameter equals fail

Receive information about instance id 1
curl -X GET 'https://domain.com/api/auth/v3/instance/1' -H 'Cookie: ses6=E7CA54FA24C8AD4F71E0761A' | jq

Automatic login to the Vepp web interface


Using an API-function, you can implement a possibility to go to the web interface of a required Vepp instance. E.g. you can use it for the button "Go to service' in the web interface in your clients' member area. 

How it works: 

  1. Log in with the permissions of the required user. E.g. with the login and password: 

    Authorization
    curl -X POST 'https://domain.com/api/auth/v3/auth' -d '{"email": "user@example.com", "password": "client_pass"}'
  2. Save the value of the session parameter from the response you have received.
  3. Request information about the instance.
  4. Save the value of the sub_domain parameter. 
  5. Make a redirect to the URL like https://sub_domain.domain.com/#/auth/ses. 

     Where

    sub_domain — the value of the sub_domain parameter that you have received on step 4. 

    ses — the value of the session parameter that you have received on step 2. 

Note.

In this case, you don't need to delete the user session after you have completed the operations.