SVGator API & SDK documentation

Using SVGator's SDKs (Software Development Kit) to interact with SVGator's API (Application Programming Interface) will allow your users to connect their SVG projects to your application.

Please note that we strongly recommend the usage of the included SDKs over direct API calls.

1. Before You Start

In order to use SVGator's API & SDKs, one first must obtain an SVGator Application. To do so, please email [email protected], providing your SVGator account ID and the desired usage of your SVGator application.

The API keys one should receive from [email protected] are shown below:

Name	Description	Notes	Sample Value
`app_id`	Application ID	prefixed with "ai_", followed by 32 alphanumeric chars	`ai_b1357de7kj1j3ljd80aadz1eje782f2k`
`secret_key`	Secret Key	prefixed with "sk_", followed by 32 alphanumeric chars	`sk_58ijx87f45596ylv5jeb1a5vicdd92i4`

❗ Attention
◾ Your Secret Key must not be included in any requests, neither be present on Front-End.

Creating an application on the fly is also possible using appId=dynamic, yet this feature comes with restrictions. For a multi-user implementation follow the steps above instead.

2. Frontend API

We encourage to use SVGator's own Frontend SDK (offered as a CDN link with a detailed example as well as a Node package) over own implementation of frontend API calls.

2.I. Connect Users with a Popup Window

Open a pop-up window from JS letting your users to connect their SVGator account to your app.

Endpoint: https://app.svgator.com/app-auth/connect
Method: GET
Parameters:

Name	Description
`appId`	your Application ID
`origin`	origin of the opener window, url encoded

Sample URL

https://app.svgator.com/app-auth/connect?appId=ai_b1357de7kj1j3ljd80aadz1eje782f2k&origin=https%3A//example.com

Success response

{
  "code":0,
  "msg":{
    "auth_code":"ac_3db45107d0833b4bb8g43a67380e51fe",
    "auth_code_expires":1606415498,
    "app_id":"ai_b1357de7kj1j3ljd80aadz1eje782f2k"
  }
}

After the user has successfully logged in to SVGator and authorized your application, the API will send the string response above as a postMessage to your window.

Success response - parameters

Name	Description
`app_id`	your Application ID
`auth_code`	your authentication code needed to generate a back-end `access_token`
`auth_code_expires`	the exiration time of `auth_code` in unix timestamp; defaults to 5 minutes

Authorization Popup - Screenshot

Click here to see how the popup will show up for your users

2.II. Connect Users through a Redirect URL

Point your users to SVGator's URL to connect their SVGator account to your app.

Endpoint: https://app.svgator.com/app-auth/connect
Method: GET
Parameters:

Name	Description
`appId`	your Application ID
`redirect`	origin of the opener window, url encoded

Sample URL

https://app.svgator.com/app-auth/connect?appId=ai_b1357de7kj1j3ljd80aadz1eje782f2k&redirect=https%3A//example.com

Success response

https://example.com/?auth_code=ac_3db45107d0833b4bb8g43a67380e51fe&auth_code_expires=1606421028&app_id=ai_b1357de7kj1j3ljd80aadz1eje782f2

After the user has successfully logged in to SVGator and authorized your application, the API will redirect them to the URL you provided, suffixed with response parameters.

Success response - parameters

Same as connecting users with a popup window.

Authorization Redirect - Screenshot

Click here to see how the redirect will show up for your users

2.III. Dynamic App Creation

This feature is intended for applications with a single user access or from pages where the owner doesn't want to have control over the application itself (an example being SVGator's Wordpress plugin).

This usecase is identical to connecting users with a popup window with the exception that one should pass appId=dynamic.

See further restrictions under obtaining an access_token.

3. Backend API

This section describes server to server API requests, available only for application already having authorized users, as described under Frontend section.

Again, we strongly recommend to use vendor backend SDKs (PHP or Node.js) over custom implementation of API calls.

3.I. Obtain an `access_token`

In order to interact with users' projects on SVGator, the next step is to obtain an access_token, which is specific to given application and to the current user.

Endpoint: https://app.svgator.com/api/app-auth/token
Method: GET
Parameters:

Name	Description
`app_id`	your Application ID, provided by SVGator
`auth_code`	the authentication code received from Frontend API
`time`	current unix timestamp
`hash`	64 chars sha256 security token; see generation details under 3.III.

Sample URL

https://app.svgator.com/api/app-auth/token?app_id=ai_b1357de7kj1j3ljd80aadz1eje782f2k&time=1606424900&auth_code=ac_3db45107d0833b4bb8g43a67380e51fe&hash=8a022f4cedc9f1145e75d50dd96021fd5da757010f000f72d4f8a358730e07f1

Success response

{
  "access_token": "at_826a1294b59a229412546cadf1b7ef66",
  "customer_id": "ci_90c94934c0fce81bddf42385f1432169"
}

Save both values for later usage. The given access token will allow you to retrieve all the SVGs for the given customer for a period of 6 months, or until the user revokes your permissions from their account settings.

3.II. Obtain an `access_token` for a Dynamic App

Generating an access_token for a Dynamic App is highly similar to the previous point, the difference being that in this case secret_key will be returned in the response, togheter with access_token and customer_id.

❗ Attention
◾ For dynamic application, each `token` request will invalidate previous `auth_codes`, yet already issued `access_tokens` will remain functional. ◾ Also to be noted that an `app_id` and `secret_key` pair obtained for a dynamic app cannot be used to gain access to other users' projects.

Endpoint: https://app.svgator.com/api/app-auth/token
Method: GET
Parameters:

Name	Description
`app_id`	your Application ID returned by Frontend authentication
`auth_code`	the authentication code received from Frontend API
`time`	current unix timestamp
`hash`	64 chars sha256 security token; see generation details under 3.III.

Sample URL

https://app.svgator.com/api/app-auth/token?app_id=ai_b1357de7kj1j3ljd80aadz1eje782f2k&time=1606424900&auth_code=ac_3db45107d0833b4bb8g43a67380e51fe&hash=8bb464918035de36f09a49dd5d247045f2e6daaee49ea97dc3fba363e39f7b39

Success response

{
  "access_token": "at_826a1294b59a229412546cadf1b7ef66",
  "customer_id": "ci_90c94934c0fce81bddf42385f1432169",
  "app_id": "ai_b1357de7kj1j3ljd80aadz1eje782f2k",
  "secret_key": "sk_ec55dda518dd823cb404g532316c09c36"
}

Save all values for later usage. secret_key must be used to generate the hash security token further on.

3.III. How to generate the `hash` security token

Each server to server request must contain a valid hash parameter, generated based on request parameters as described below. Let's consider as an example the access_token request from 3.I. As a first step, collect all parameters from a given request, which for this example will be the following:

Name	Value
`app_id`	`ai_b1357de7kj1j3ljd80aadz1eje782f2k`
`time`	`1606424900`
`auth_code`	`ac_3db45107d0833b4bb8g43a67380e51fe`

Sort the parameters alphabetically by their names:

Name	Value
`app_id`	`ai_b1357de7kj1j3ljd80aadz1eje782f2k`
`auth_code`	`ac_3db45107d0833b4bb8g43a67380e51fe`
`time`	`1606424900`

Next, concatenate their values (without any separator):

ai_b1357de7kj1j3ljd80aadz1eje782f2kac_3db45107d0833b4bb8g43a67380e51fe1606424900

The next step is appending secret_key, but there is an exception for that - obtaining an access_token for a Dynamic App (3.II.). That is the single request in which case secret_key should not be used for hash generation, since it is not yet available to the API client.

In that case, secret_key should be considered an empty string, yet hash still needs to be generated. In all other cases, the secret_key (either recieved from SVGator or returned by dynamic app token request) should be appended to the given string.

❗ Attention
◾ The `secret_key` itself should never be added to any of the URLs.

For the sake of the example, let's assume your secret_key is sk_ec55dda518dd823cb404g532316c09c36, which appended to the end of the current hash will result in:

ai_b1357de7kj1j3ljd80aadz1eje782f2kac_3db45107d0833b4bb8g43a67380e51fe1606424900sk_ec55dda518dd823cb404g532316c09c36

Now generate the sha256 hash of the given string:

8a022f4cedc9f1145e75d50dd96021fd5da757010f000f72d4f8a358730e07f1

Use the result string as &hash= parameter in the request. Find examples on how to generate a hash in PHP here, respectively Node.js here.

3.IV. List of SVG Projects

Retrieve all SVG projects for a given user.

Endpoint: https://app.svgator.com/api/app-auth/projects
Method: GET
Parameters:

Name	Description
`app_id`	your Application ID
`access_token`	the access token received from `token` request, specific to the given user
`customer_id`	the customer you want to get the list of projects for; `customer_id` received from `token` request
`time`	current unix timestamp
`hash`	64 chars sha256 security token

Sample URL

https://app.svgator.com/api/app-auth/projects?app_id=ai_b1357de7kj1j3ljd80aadz1eje782f2k&time=1606424900&access_token=at_826a1294b59a229412546cadf1b7ef66&customer_id=ci_90c94934c0fce81bddf42385f1432169&hash=df711b4e3626d65d256842d28b43d89196f09e5ac2a772ce2e882bdb655a2bf8

Success response

{
    "projects": [
        {
            "id": "pi_scf57osvhoc2hptnmqap79lvfdpld9xi",
            "title": "Web Dise\u00f1o",
            "preview": "https://cdn.svgator.com/project/m7/50/07gorpgkdpm6m6dnwq03oyfb1kej/prv.svg",
            "created": 1606300441,
            "updated": 1606300711
        },
        {
            "id": "pi_uinfb7kl855j2yxpbsglty0eo28yd8jp",
            "title": "SAMPLE PROJECT1",
            "preview": "https://cdn.svgator.com/project/4h/xx/6cjqkpmvz8fasvp1ch2vfavcgw5o/prv.svg",
            "created": 1606137253,
            "updated": 1606137253
        },
    ]
}

Only 2 sample projects are listed above, but please note that given request will return all projects of the current user.

Use projects[i]->id in further requests to obtain up to date details of the given project
title will hold the name of the project, given by its owner (the current user)
preview points to a static version of the SVG projects to be used in previews and thumbnails
created & updated fields are unix timestamps

3.V. Details of an SVG Project

Retrieve details about a given SVG project of the current user.

Endpoint: https://app.svgator.com/api/app-auth/project
Method: GET
Parameters:

Name	Description
`project_id`	the ID of the SVG project, retreived by the previous request
`app_id`	your Application ID
`access_token`	the access token received from `token` request, specific to the given user
`customer_id`	the customer you want to get the list of projects for; `customer_id` received from `token` request
`time`	current unix timestamp
`hash`	64 chars sha256 security token

Sample URL

https://app.svgator.com/api/app-auth/project?project_id=pi_scf57osvhoc2hptnmqap79lvfdpld9xi&app_id=ai_b1357de7kj1j3ljd80aadz1eje782f2k&customer_id=ci_90c94934c0fce81bddf42385f1432169&access_token=at_826a1294b59a229412546cadf1b7ef66&time=1606424900&hash=8faa921320977dec53a206411e115cf82fddd0906c9af531682d298048ff77f8

Success response

{
    "project":
    {
        "id": "pi_scf57osvhoc2hptnmqap79lvfdpld9xi",
        "title": "Web Dise\u00f1",
        "preview": "https://cdn.svgator.com/project/m7/50/07gorpgkdpm6m6dnwq03oyfb1kej/prv.svg",
        "label": "TEST LABEL",
        "created": 1606300441,
        "updated": 1606300711
    }
}

label field denotes the tag given to the project by its owner and it is optional. The rest of the response fields are identical to project list response.

3.VI. Export an Animated SVG Project

Retrieve the animated SVG project of the user as raw text.

Endpoint: https://app.svgator.com/api/app-auth/export
Method: GET
Parameters:

Name	Description
`project_id`	the ID of the SVG project, retreived by a previous request or stored locally
`app_id`	your Application ID
`access_token`	the access token received from `token` request, specific to the given user
`customer_id`	the customer you want to get the list of projects for; `customer_id` received from `token` request
`time`	current unix timestamp
`hash`	64 chars sha256 security token

Sample URL

https://app.svgator.com/api/app-auth/export?project_id=pi_scf57osvhoc2hptnmqap79lvfdpld9xi&app_id=ai_b1357de7kj1j3ljd80aadz1eje782f2k&customer_id=ci_90c94934c0fce81bddf42385f1432169&access_token=at_826a1294b59a229412546cadf1b7ef66&time=1606424900&hash=8faa921320977dec53a206411e115cf82fddd0906c9af531682d298048ff77f8

Success response

Content-Type: image/svg+xml

   <svg id="egain0g46a2d1" ...>
      ...
      <script>...</script>
   </svg>

The response will be raw text, containing the SVG data. Save such projects locally and update them periodically or on user's action. Serve the saved version to actual end-users and/or in a web page.

3.VII. Error Handling

In case of error HTTP response will remain 200 and the body of the request will hold the JSON object below:

{
    "error": "Here comes the error message",
    "error_description": "This is an optional description. Most of the cases this property is missing."
}

All responses should be validated against the given structure. HTTP response codes different than 200 might also appear in case of a network issue.

4. Further Resources

Frontend SDK:

SVGator Frontend SDK documentation 🔗 is avaiable on Github, as well as a usage example 🔗
SVGator Frontend SDK is also available as @svgator/sdk-frontend 🔗 Node package

Backend SDK:

SVGator provides a PHP Backend SDK available on Github 🔗
Node.js version is also available through npm as @svgator/sdk-backend 🔗

For further support & questions, feel free to contact us at [email protected].

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
assets		assets
dist		dist
react-native		react-native
svgator-backend		svgator-backend
svgator-frontend		svgator-frontend
svgator-php		svgator-php
svgator_player_flutter		svgator_player_flutter
.gitignore		.gitignore
ExportException.php		ExportException.php
README.md		README.md
command-line-control.js		command-line-control.js
package-lock.json		package-lock.json
package.json		package.json
webpack.config.js		webpack.config.js

SVGator/SDK

Folders and files

Latest commit

History

Repository files navigation

SVGator API & SDK documentation

Table of Contents

1. Before You Start

2. Frontend API

2.I. Connect Users with a Popup Window

Sample URL

Success response

Success response - parameters

Authorization Popup - Screenshot

2.II. Connect Users through a Redirect URL

Sample URL

Success response

Success response - parameters

Authorization Redirect - Screenshot

2.III. Dynamic App Creation

3. Backend API

3.I. Obtain an access_token

Sample URL

Success response

3.II. Obtain an access_token for a Dynamic App

Sample URL

Success response

3.III. How to generate the hash security token

3.IV. List of SVG Projects

Sample URL

Success response

3.V. Details of an SVG Project

Sample URL

Success response

3.VI. Export an Animated SVG Project

Sample URL

Success response

3.VII. Error Handling

4. Further Resources

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Languages

3.I. Obtain an `access_token`

3.II. Obtain an `access_token` for a Dynamic App

3.III. How to generate the `hash` security token

Packages