Webasyst resources server API

Contents...

Before sending requests to the API in your server-side or client app, first obtain an authorization token from the Webasyst authorization server.

Method

Obtain user’s personal information

HTTP requests

  • GET: https://www.webasyst.com/id/api/v1/profile/

Required permissions

  • profile

Response format

{
    "name":"Bull Name",
    "firstname":"First Name",
    "lastname":"Last Name",
    "middlename":"Middle Name",
    "userpic":"https://{absolute URL of the uploaded 96x96 pixels size user photo}",
    "userpic_original_crop":"https://{absolute URL of the uploaded original size user photo}",
    "userpic_uploaded":{true or false},    //whether the user has a photo uploaded in their profile
    "email":[    //array of email addresses
        {
            "value":"name@domain.com",              //email address
            "ext":"work",                           //optional address type
            "status":{"confirmed" or "unknown"}    //address status
        },
        {
            "value":"...",
            "ext":"...",
            "status":"..."
        }
    ],
    "phone":[    //array of phone numbers
        {
            "value":"11001234567",                  //phone number
            "ext":"work",                           //optional phone number type
            "status":{"confirmed" or "unknown"}     //phone number status
        },
        {
            "value":"...",
            "ext":"...",
            "status":"..."
        }
    ]
}

Edit user’s personal information

HTTP requests

  • POST/PUT/PATCH: https://www.webasyst.com/id/api/v1/profile/

POST and PUT requests are send identically and result in the full overwriting of all profile data. If some of the specified values are not added to the request then empty strings are saved to the user profile.

When the PATCH request is used then only the specified fields’ values are updated while missing ones remain unchanged.

Required permissions

  • profile:write

Data format (JSON)

{
    "firstname": "...",
    "lastname": "...",
    "middlename": "...",
    "email": ["...", "..."],
    "phone": ["...","..."]
}

Response format

In case of success the resources server returns a response with the 200 code and the same format which is used for GET requests at this URL.

Obtain the list of Webasyst accounts in whose backends the user has enabled sign-in with Webasyst ID

HTTP requests

  • GET: https://www.webasyst.com/id/api/v1/installations/

Required permissions

  • profile

Response format

The client_id field contains the identifiers of the accounts with which they are registered on the authorization server. Not the same as a client_id of a client app!

[
    {
        //main fields
        "id":"{client_id of a Webasyst account}",
        "domain":"{account’s domain name}",
        "url":"{account’s absolute URL}",

        //extra fields available only on Webasyst Cloud:
        "cloud_plan_id":"...", //plan identifier
        "cloud_expire_date":"...", //paid period’s expiration date
        "cloud_trial":"...", //whether the account is free, i.e. has never been paid for
        "cloud_name":"...", //technical account name, available only to the account owner
        "cloud_data":{...} //optional extra account data
    },
    {
        ...
    }
]

Upload a new photo to the user’s profile

HTTP requests

  • POST: https://www.webasyst.com/id/api/v1/profile/userpic/

Required permissions

  • profile:write

Data format

The request body must contain the binary contents of the uploaded photo file. Acceptable image file formats, for which the format description must be added to the Content-type header, are as follows:

  • JPEG (format description: image/jpeg),
  • PNG (format description: image/png).

Response format

In case of success the resources server returns a response with the 201 code and data in the following format:

{
    "userpic": "....", //URL of a 96x96 pixels size photo thumbnail
    "userpic_original_crop": "...." //URL of a cropped version of the uploaded photo
}

Delete the photo from the user’s profile

HTTP requests

  • DELETE: https://www.webasyst.com/id/api/v1/profile/userpic/

Required permissions

  • profile:write

Response format

In case of successful photo deletion the resources server return a response with the 204 code.

Obtain the list of licenses belonging to the user

HTTP requests

  • GET: https://www.webasyst.com/id/api/v1/licenses/

Required permissions

  • license:read

Response format

[
    {
        "license_id":"{license identifier}",
        "slug":"{software product’s search identifier}",
        "product_id":"{software product’s numeric identifier}",
        "order_id":"{license purchase order number}",
        "app_id":"{identifier of the app the which the product belongs}",
        "ext_id":"{extra identifier of a plugin, widget or design theme}",
        "type":"{software product type:  APP, PLUGIN, THEME or WIDGET}",
        "name":"{product name}",
        "expire_date":{expiration date and time of a hosted product license, if available},
        "bound_to":"{domain name of the Webasyst account to which the license is linked}",
        "bind_available_date":{date when the license can be re-linked to another account, if this option is temporarily unavailable}
    },
    ...
 ]

Create a Webasyst Cloud account

The created account will start working with the trial plan with a limited free period.

HTTP requests

  • POST: https://www.webasyst.com/id/api/v1/cloud/signup/

Required permissions

  • Not required.

Request format

JSON or ordinary form-data.

Parameters

  • bundle (optional): identifier of the app bundle which will initially be available in the account:
  • userdomain (optional): beginning of the domain name, entered by a user, starting with .webasyst.cloud. If no value has been specified then it is generated automatically.
  • account_name (optional): company name entered by a user, which can be used in the account settings and displayed on the website.

Response format

In case of successful creation of the first free account for the specified used, the resources server return a response in the following format:

{
    "id":"...", // client_id of the Webasyst account
    "domain":"...", // account’s domoain
    "url":"...", // account’s full URL
    "auth_endpoint": "...", // one-time backend login URL not requiring authorization
    "cloud_plan_id":"...", // plan identifier
    "cloud_expire_date":"2030-01-01", // account’s period expiration date
    "cloud_trial":true, // whether the account is free, i.e. has never been paid for
    "cloud_name":"w123456-7890" // technical account name
}

In case of an attempt tp create another account of the same server the resources server returns a response in the following format, with the 409 code:

{
    "error":"already_exists", // flag denoting that the user already has a free account
    "error_description":"..." // error message
}

Add a custom technical domain to a Webasyst Cloud account

The method adds an extra subdomain of the form xxxxxx.webasyst.cloud on which the account must be available in addition to its default technical domain.

The address change occurs not immediately because sending a request only adds a task to an asynchronous queue. The actual execution of the task may take up to several minutes.

The method is available only to the account owner. The availability of this method can be determined by the availability of the cloud_name field in the account properties, which can be obtained using the method for obtaining the list of Webasyst accounts in whose backends the user has enabled sign-in with Webasyst ID.

HTTP requests

  • POST: https://www.webasyst.com/id/api/v1/cloud/rename/

Required permissions

  • Not required.

Request format

JSON or ordinary form-data.

Parameters

  • client_id: account’s client_id,
  • domain: default subdomain’s name part before the period character in an address of the form xxxxxx.webasyst.cloud.

Response format

In case of successfully added subdomain the resources server returns an empty response with the 204 code.

Activate a product license for a Webasyst account

The method is available only when the client app’s developer is the same as the Webasyst product’s developer.

HTTP requests

  • POST: https://www.webasyst.com/id/api/v1/licenses/force/

Required permissions

  • Not required.

Request format

JSON or ordinary form-data.

Parameters

  • client_id: Webasyst account’s client_id,
  • slug: search identifier of the software product.

Response format

  • If the product is already activated in the account then the resources server returns an empty response with the 204 code.
  • If the product is not activated in the account then the resources server activates its any non-activated available license and returns an empty response with the 204 code.
  • If the developer has no non-activated license then the resources server creates a temporary trial license, activates it for the specified account, and returns an empty response with the 204 code. Such a license remains valid during 1 month.

In case of an error the resources server returns an error message in the following format:

{
    "error": "...", //numeric error code
    "error_description": "...", //error message
}

Error response codes:

  • 400: an existing client_id has been specified which is not a client_id of a Webasyst account and is a client_id of another resource such as a website or a mobile app,
  • 403: the error cause is described in the "error" field of the response body:
    • product_not_allowed: the client app’s developer is not a Webasyst product developer,
    • invalid_token_client: the request has not been sent from a client app.
  • 404: the error cause is described in the "error" field of the response body:
    • installation_not_found: non-existent client_id is specified,
    • product_not_found: no product with the specified slug exists.

Obtain a code to merge profiles

HTTP requests

  • GET: https://www.webasyst.com/id/api/v1/profile/mergecode/

Required permissions

  • Not required.

Response format

The server returns response in the following format with the 200 code:

{
    "code":"...", // code for merging profiles
    "expires":... // UNIX timestamp of the moment until which profiles are allowed to be merged
}

Response format in case of an error:

  • 409 (empty response body): A contact is not available, only user profiles created more than 1 day ago can be merged.

Obtain profiles merging results

HTTP requests

  • GET: https://www.webasyst.com/id/api/v1/profile/mergeresult/

Required permissions

  • Not required.

Response format

The server returns a response in the following format with the 200 code:

  • If merging was completed successfully: 
    {
    "status":"success",
    "description":"..."
}
  • if merging failed: 
    {
    "status":"not_attempted",
    "description":"..."
}
{
    "code":"...", // code for merging profiles
    "expires":... // UNIX timestamp of the moment until which profiles merging can be completed
}

Response format in case of an error:

  • 409 (empty response body): A contact is not available, only user profiles created more than 1 day ago can be merged.

Withdraw previously issued permissions to send user-related requests

HTTP requests

  • DELETE: https://www.webasyst.com/id/api/v1/delete/

Required permissions

  • Not required.

Response format

{
    "delete":true
}