For Vepp admin

Guide to API Vepp

General information 


API URL

You can access the API by the URL https://domain.com/service/api_version/function/

 Where

domain.com — public IP address or the domain of the server with Vepp. 

service — request processing service: auth. 

api_version — current version API: v3.

function — function that should be executed in Vepp.

HTTP-requests methods 

Vepp supports GET, POST, and DELETE.

POST-request methods 

To send parameters for a POST-request, specify them in the request body in the JSON format. 

Response format

A response to API-requests is sent in the form of JSON-objects, e.g.:

Error notification in JSON
{
  "error":
  {
    "code": <error internal code, int>,
    "msg": <error notification, string>,
    "value": <additional informaion, object>
  }
}

How to process code 503


If Vepp is not active for a long time it can be suspended. API-requests will be terminated with code 503. Repeat requests until you receive another code: 

Example on Python 3
def retry(fn, **kwargs):
    response = fn(**kwargs)
    if response.status_code == 503:
        for attempt in range(1, 11):
            time.sleep(0.1 * attempt)
            logging.info(f'Try connect to {kwargs["url"]} number {attempt}')
            response = fn(**kwargs)
            if response.status_code != 503:
                break
    return response

def internal_post(url, data):
    headers = {"Host": "instance-" + os.environ["INSTANCE_ID"], "internal-auth": "on"}
    logging.info(f'Try connect to {url} with headers {headers}')
    retry(requests.post, url=url, json=data, headers=headers)

Authentication methods 


There are three levels of functions: 

  • public function  — they can be called without authentication;
  • user functions  —  user with the "User" access permissions can call the functions;
  • administrator functions  — user with the "Admin" access permissions can call the functions;

In order to check the user level, Vepp tries to find the ses6 cookie-file in the HTTP-heading. It should contain the id of the current sessions of the user. To receive the session id, use the login/password or key authentication. 

Login and password authentication

  1. To receive a session number, send the POST-request to a URL like https://domain.com/api/auth/v3/auth

    Request body in JSON
    {
      "email": your_email,
      "password": your_password
    }
  2. Process the response. It can contain error messages or JSON like: 

    Response in JSON
    {
      "expires_at": string,
      "id": int,
      "session": string
    }
  3. Use the session number that you have received in the heading of the HTTP request. E.g.:

    Usage in curl
    curl -k -H "Cookie:ses6=F2BABF12426B297C86FC5628" 'https://domain.com/api/auth/v3/user_exist/client@example.com'
  4. In the case of error you will receive the following message: 

    Authentication error
    {
      "error":
      {
        "code": 1114,
        "msg": "Whoami verifired error",
        "value":
        {
          "code": 3002,
          "msg": "Session not found"
        }
      }
    }

Key authentication 

Vepp supports throughout user authentication with admin login and password. Eg. it can be used to redirect authorized users from BILLmanager to Vepp.

How it works:

  1. Send a POST-request to create a key with Admin permissions: 

    Create an authentication key
    curl -X POST 'https://domain.com/api/auth/v3/user/client@example.com/key' -H 'Cookie: ses6=E6900A56BE7DF0FB28ED7BE7' -d '{}'| jq
  2. You will receive a JSON-object something like this: 

    Response in JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "key": "94DA5B99AF0BF26D2E96458CABA8DA96"
    }
  3. To get the session number, send the POST-request  with the key you have received: 

    Receive the session number by the key
    curl -X POST 'https://domain.com/api/auth/v3/auth_by_key' -d '{"key": "94DA5B99AF0BF26D2E96458CABA8DA96"}'| jq
  4. You will receive the JSON-object something like this: 

    Response in JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "id": 2,
      "session": "CC033C4629BAEF3852CFE27A"
    }

Managing the current session 


Receive information about the current session

  1. Send a GET-request with the number of the current session: 

    Receive informaion about the current session
    curl -X GET 'https://domain.com/api/auth/v3/whoami' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. You will receive the JSON-object something like this: 

    Response in JSON
    {
      "expires_at": "2019-12-21 23:59:59",
      "lang": "ru",
      "owner_email": "client@example.com",
      "owner_id": 2,
      "roles": [
        "@user"
      ],
      "ses_id": 2,
      "session": "CC033C4629BAEF3852CFE27A",
      "trustee_email": "client@example.com",
      "trustee_id": 2
    }

Terminate the session 

We recommend terminating the user session after you have completed your API operations: 

  1. Send a DELETE-request with the session number:

    Close the session
    curl -X DELETE 'https://domain.com/api/auth/v3/session/CC033C4629BAEF3852CFE27A' -H 'Cookie: ses6=CC033C4629BAEF3852CFE27A' | jq
  2. You will receive the JSON-object something like this: 

    Response in JSON
    {
      "status": "ok"
    }
  3. When trying to use the deleted session you will receive the JSON-object something like the following: 

    Session not found
    {
      "error": {
        "code": 3002,
        "msg": "Session not found"
      }
    }

Error codes


Error codeHTTP codeError typeDescription that will be returnedDescription
3001401AuthInvalidLoginInvalid login

An invalid login or password has been specified for authentication.  

3002401AuthSessionNotFoundSession not foundA non-existent code of the session has been sent.
3003404AuthUserNotFoundUser not foundThe specified user is not found. 
3004409AuthUserAlreadyExistUser already existsThe specified user already exists. 
3005403AuthAccessDeniedAccess denied

Insufficient permissions to complete the operation.

3007401IspSessionHeaderNotFoundSession header was not setThe user session id has not been sent in the request heading.
3014403AccessForbiddenAccess forbiddenAccess is denied for the specified user.
3015401TooFrequentLoginAttemptsToo frequent login attemptsThe number of invalid authentication attempts has been exceeded. 
3016404AuthKeyNotFoundTemporary identification key not foundThe specified one-time authentication key does not exist or has been already used. 
3018403AuthAccountDisabledAccount is disabledThe user account has been blocked. 
3051404ProductNotFoundProduct not found

An invalid parameter value of the product instance has been sent.

3080404InstanceNotFoundInstance not foundVepp instance with the specified id doesn't exist.