Using the Zercurity Hawk API with Postman

Zercurity
4 min readSep 20, 2022

--

Zercurity is an API first platform. Which means everything that’s possible in the frontend (used by you). Can be programmatically accessed via the Zercurity API in the backend.

Getting Started

The entire API documentation is available here:

https://api.zercurity.com
The Zercurity API

From the left hand side you can see all of the available grouped resources which can be interacted with. Navigating through this menu will show you the available methods and parameters available for a given API request. Including examples. If you want to make life easy for yourself — Zercurity works with Postman.

Postman

Postman is a fantastic web and desktop app for building and consuming APIs. To consume the Zercurity API, first create a new workspace.

Creating a new workspace within Postman

Provide a name and description and visibility scope for your new Workspace.

Workspace configuration for Postman

Upon creating the workspace. Choose import just next to your project name. From here we’ll be able to import the Swagger YAML file. Swagger is a standardised YAML (OpenAPI) format for exporting and sharing API schemas. Providing portability and code automatically generated from the schemas.

https://api.zercurity.com/swagger.yaml

The swagger file is available directly from https://api.zercurity.com using the download button.

Providing the Swagger YAML file for the Zercurity Postman API

Once imported, we recommend that you select API resources be organised by Tags. This will help better organise and group the APIs based on the Tags provided by Swagger. Everything else can be left as its default.

Importing the Zercurity Swagger API into Postman

Once complete you’ll see all the API resources appear in the left hand menu.

Generating our Zercurity API token

In order to authenticate with the Zercurity API. You’ll need an API Access Id and Access Key. From within Zercurity, go to Settings and the API keys. From here create a new API key and give it a name. We’re using Postman. Once you hit create you’ll receive your new API keys.

Important

Keep these API keys safe. Once the dialogue box disappears, the API keys cannot be retrieved. To limit and/or grant access to a given API you’ll need to define a new or use an existing IAM policy template.

Creating a new Zercurity API key

Once you’ve setup your API key head on over to the Zercurity API heading and under the Authorization tab make sure the Authentication type is set to Hawk Authentication. The algorithm can remain as SHA256. Lastly, at the very bottom under the advanced heading ensure that include payload hash is checked.

Providing postman with the Hawk authentication keys

A few tabs over you can also provide the API URL path. You won’t need to change this. However, if you’re using Zercurity on-prem, in a different region or a managed instance you’ll need to change the URL to match your environment.

Configuring the Zercurity environment

Once done, you’re good to go. The quickest API request you can make is to see what companies are available to you under your API key.

/companies
Making your first Zercurity API request

Its all over!

We hope you found this helpful. Please feel free to get in touch if you have any questions.

--

--