Quick Start

Basics

The base API is accessible at:

https://api.zenginehq.com/v1/

Data can be both sent & received in JSON & XML formats.

Auth

The OAuth 2 protocol is used to authenticate and authorize every API request.

There are two types of requests you may want to make, both requiring different sets of credentials:

Public: A request made by your application for publicly accessible data. Often referred to as 2-legged auth because there are 2 parties involved: the API and your application.
Private: A request made by your application on behalf of a third-party user. Often referred to as 3-legged auth because there are 3 parties involved: the API, your application, and the user your application is acting on behalf of.

Most resources in the Zengine API are private.

To access public resources, you will need to provide an API key in the query string of your request:

?client_id={your API key}

To access private resources, you will need to provide an access token for the user you are acting on behalf of (even if that user is yourself).

?access_token={user's access token}

Getting an API Key

You can retrieve any API key by creating a user, and then using the access token returned to you to create an API client. Take note of the key that is returned to you. It cannot be retrieved again.

Getting an Access Token

Access token flows can get quite complicated. They vary depending on who the user is, how your application interacts with that user, and other nuanced requirements.

To fully understand which flows apply to your use case and how to implement them, we suggest reading more about the API's Auth process at large.

For now, to get you started with a sample request, we will assume that you are trying to access data from your own account with a token that you manually acquire for the purposes of this demo. When you are ready, proceed to login and retrieve your demo token.

Example Request

Now that you have an API key and demo access token, you are ready to make both public and private API requests.

Let's start with a private request (the most common). For example, all of the Workspaces you are associated with in JSON format:

https://api.zenginehq.com/v1/workspaces.json?access_token={your demo access token}

For public requests, such as retrieving a list of AppTemplates from the marketplace, you must instead supply your API key. Simply point your browser to:

https://api.zenginehq.com/v1/app_templates.json?client_id={your API key}

That's all there is to it! From here on out, we suggest learning by doing. The resources are not only documented, but also interactive. You can peruse them to learn the API semantics and make real requests (take note of your API key and access token, because you'll need them!). As you want or need, the rest of the documentation is here to help you learn more about general API conventions, tools and details that may prove useful for specific application requirements.