We recommend using the free tool Postman for accessing the City API (CNAPI2, pronounced 'canopy two'). The tool can be downloaded at https://www.getpostman.com/downloads/.

Once you have Postman installed, you'll have a blank workspace:

You'll need to import the Exaptive CNAPI2 Postman collection and Postman environments. Click on the link below to go to our postman documentation portal. 

CNAPI2 Postman Collection, Environment, and Documentation

On the Postman documentation page, click the "Run in Postman" button on the top-right corner of the screen. This will download and import both the collection and environment directly into your local Postman workspace:

After the files have been imported, you should have the CNAPI2 collection in your workspace menu on the left, and the blank CNAPI2 environment file in the environment dropdown list in the upper right:

Now you'll need to configure your environment files to point to your city, and to contain the correct authentication credentials. Select the CNAPI2 Environment from the dropdown in the upper right, and click on the eye icon to inspect the environment variables. Edit the current value fields to set the api field to the top-level url for your city, and add the city-UUID provided by your city administrator. Set the email and password fields with the credentials for your account: 

Note that this guide focuses on authenticating with your username and password. If you were given an API key with specific permissions, you can skip the rest of the steps outlined in this guide. Instead, edit your environment so that the "use-api-key" variable is set to "true" and you fill in the "api-key" variable with your key:

Now test out each environment configuration to make sure you can successfully authenticate. There is an 'Authentication' folder at the top-level of the Postman CNAPI2 collection. Select the 'Login' method:

Click the 'Send' button. You should get a JSON return payload back with a 'success' status:

Once you are authenticated, you can start using the other methods of the API. If you try to make an API call without authenticating first, you will receive a "Failed to Authorize" error in the returned JSON payload. The City API uses Javascript Web Tokens (JWTs) to secure api calls. These tokens will expire after an hour so if you find that your API calls suddenly starts giving you an authorization error, go back to the appropriate authentication method and re-authenticate to receive a new token.

Next Steps: