Generating a Private Key

To access the Zube API, you first need to generate a private key. You will then use this private key to sign access token requests.

1. Log in to Zube, navigate to your profile settings page and click on the API Access tab.
2. Click the 'Generate an API Key' button. You will be prompted to download a .pem file containing your Private API Key. Click save.

   Make sure to store this file! Zube only stores the public portion of the key and you will not be able to view this key again.

3. After you've generated your first private key, you will be issued a Client Id. You will also be shown the fingerprint for your private key, which you can use to verify the key if you wish.

Requesting an API Access Token

Before you can send requests to Zube's API endpoints, you will need an access token. Before you can request an access token from Zube, you will need to create a refresh JSON Web Token (JWT) signed by your private key and encoded using the RS256 algorithm. Zube checks the key of this refresh JWT against the public key stored by Zube and returns a new access JWT that you use to access all other API endpoints.

var fs = require('fs');
var jsonwebtoken = require('jsonwebtoken'); // $ npm install jsonwebtoken

var client_id = CLIENT_ID;
var private_key = fs.readFileSync(PATH_TO_PEM_FILE);

var now = Math.floor(Date.now() / 1000);
var refresh_jwt = jsonwebtoken.sign({
    iat: now,      // Issued at time
    exp: now + 60, // JWT expiration time (10 minute maximum)
    iss: client_id // Your Zube client id
}, private_key, { algorithm: 'RS256' });

console.log(refresh_jwt);

Replace CLIENT_ID and PATH_TO_PEM_FILE in the above code with your information.

The code above creates a refresh JWT with a one minute expiry. You can create your refresh JWT with an expiry of up to 10 minutes. Once your refresh JWT is expired, you will need to generate a new refresh JWT to request new access tokens.

After creating the refresh JWT, you can request a new access token. Set your refresh JWT and Client Id in the Header of the API request to the tokens endpoint:

curl -i \
-H "Authorization: Bearer REFRESH_JWT" \
-H "X-Client-ID: CLIENT_ID" \
-H "Accept: application/json" \
-X POST \
https://zube.io/api/users/tokens

REFRESH_JWT and CLIENT_ID are the values you must replace.

The API request above will return an access token, your ACCESS_JWT, which you can use to make further requests to Zube's API endpoints.

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
-H "Accept: application/json" \
https://zube.io/api/ANY_END_POINT

NOTE: The access JWT in only valid for 24 hours, after which you will need to request a new access token by repeating the steps outlined above.

Verifying a Private Key

Zube generates a fingerprint for your private and public key pair using a SHA-1 hash function. You can verify that your private key matches the public key stored on Zube by generating the fingerprint of your private key and comparing it to the fingerprint displayed on Zube. To verify your private key:

1. Generate the fingerprint for your private key locally with the following command:

   openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha1 -c

2. Compare the resulting fingerprint to the fingerprint displayed on Zube for your private key. They should match.

Deleting a Private Key

You can remove a lost, compromised or unwanted private key by deleting it in the Zube interface. After you have deleted your private key, you will be able to generate a new one.

Example Request

You can find instructions for getting your CLIENT_ID and generating your ACCESS_JWT in the Authentication section above.

To send a request to a Zube API endpoint, include your ACCESS_JWT and CLIENT_ID in the Header for your request.

The code below will send a GET request to the projects endpoint.

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
-H "Accept: application/json" \
https://zube.io/api/projects

Example Response

The code above will return a JSON object:

{
  "pagination":{
    "page":1,
    "per_page":30,
    "total_pages":1,
    "total":1
  },
  "data":[
    {
      "id":123456,
      "account_id":54321,
      "description":"The place to organize our web application",
      "name":"Web Project",
      "created_at":"2018-07-06T03:52:29.513Z",
      "updated_at":"2018-07-06T03:52:29.513Z",
      "slug":"web-project",
      "private":true,
      "priority_format":"number",
      "priority":true,
      "points":true,
      "triage":false,
      "upvotes":false,
      "sources":[
        {
          "id":123456789,
          "github_owner_id":87654321,
          "description":"Javascript frontend repository",
          "full_name":"zubeio/js-frontend",
          "homepage":null,
          "html_url":"https://github.com/zubeio/js-frontend",
          "name":"js-frontend",
          "private":true,
          "created_at":"2018-09-13T19:53:09.000Z",
          "updated_at":"2019-07-02T22:25:48.000Z",
          "webhook_verified_at":"2019-07-03T23:29:09.894Z",
          "initial_import_at":"2018-12-17T04:09:49.348Z"
        }
      ],
      "workspaces":[
        {
          "id":654321,
          "project_id":123456,
          "description":null,
          "name":"Product Team Workspace",
          "slug":"product-team-workspace",
          "private":true,
          "priority_format":"number",
          "priority":true,
          "points":true,
          "upvotes":false,
          "created_at":"2018-12-17T04:09:49.348Z",
          "updated_at":"2018-12-17T04:09:49.348Z",
          "archive_merged_prs":false,
          "use_category_labels":false
        }
      ]
    }
  ]
}

Pagination

Most endpoints that return lists will return their data as paginated collections defaulting to 30 items per page. You can specify further pages by passing the page parameter. For pages that allow customized pagination, you can set the number of results per page with the per_page parameter.

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
"https://zube.io/api/cards?page=2&per_page=10"

Ordering

Most endpoints that return lists accept order[by] and order[direction] parameters. order[direction] accepts either asc or desc. The possible attributes available for order[by] can be found in the table below the endpoint description.

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
"https://zube.io/api/cards?order%5Bby%5D=points&order%5Bdirection%5D=desc"

Filtering

Most endpoints that return lists can be filtered using where. For endpoints that support filtering, the attributes available for where appear in the table below the endpoint. All filtering is scoped under the where query parameter. For example, you'd use where[project_id] to filter for a direct match of cards that are on the specified project.

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
"https://zube.io/api/cards?where%5Bproject_id%5D=3"

Select

For most endpoints that return lists you can specify which data attributes you'd like included in the response using the select parameter. select takes an array of attributes. For example to select just the id and title attributes of cards you'd use select[]=id&select[]=title

Note: For convenience, many models return with some of their associated models populated. For endpoints where a model returns with associated model data, the associated data will not be removed when a request includes select, so select may be of limited use in those cases.

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
"https://zube.io/api/cards?select%5B%5D=id&select%5B%5D=title"

Conditional requests

Most responses will return with an ETag header. You are highly encouraged to make use of ETags for subsequent requests to the same endpoint. If the response would be the same, a 304 Not Modified will be returned instead.

For example, if you received a response to the cards endpoint with the response header ETag: "27e-BpOwiFj52s046/zdOTfiQ0fepw8", then you'd include it as the value of the request header If-None-Match for subsequent requests like so:

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
-H 'If-None-Match: "27e-BpOwiFj52s046/zdOTfiQ0fepw8"' \
https://zube.io/api/cards

Body Data

When body data is sent for POST or PUT requests, it should be sent as valid JSON. Any request that sends body data should also include the required header "Content-Type: application/json".

curl -i \
-H "Authorization: Bearer ACCESS_JWT" \
-H "X-Client-ID: CLIENT_ID" \
-H "Content-Type: application/json" \
-d '{"project_id":YOUR_PROJECT_ID,"title":"Hello World"}' \
-X POST \
https://zube.io/api/cards

Rate Limiting

You can can make at most one (1) request per second. While short bursts of a few requests at a slightly higher rate are permitted, exceeding one request per second for any extended duration will result in rejection of your requests and may constitute abuse.

Abuse

Never make concurrent requests or make requests at a rate faster than one per second. If you accidentally hit the rate limit, please back off the rate of your requests immediately. If you happen to trigger abuse detection, please do your best not to trigger it again. Failure to observe these rules will result in rejection of your requests and possible suspension from future API usage.