Learn where your Karbon API key lives in Karbon, and how to create your first call to an end point in Postman.

Custom applications that interact with the Karbon API will need your tenant's API access key before they can interact with your data. Here's how to find it in 3 easy steps:

1. Register your app

Head to https://developers.karbonhq.com and register your new app. Your app will need to have its registration approved before you can retrieve your tenant API access key.

2. Log in to Karbon and go to your connected apps settings

Log into Karbon and go to 'Settings' in the sidebar, then click 'Connected Apps'
​

3. Find your custom integration and click "Manage"

Your API key will be displayed on the following page. Use this key in conjunction with your Application Authorization Token to interact with the Karbon API.

Note: Remember to only give this access key to people and applications that you trust.

Ok, so you've registered for the Karbon API and you have your Application Key and your API Key. Now it's time to get up and running. The most common API testing application seems to be Postman these days, so here's a rundown utilizing that tool.

1. Open Postman and begin by downloading the OpenAPI spec from developers.karbonhq.com.

Drag and drop the downloaded OpenAPI spec into the Postman Import dialog box.

If everything has been input correctly, you should see a new collection in Postman:

2. Adding access and API key

We'll create an Environment and add these important access keys in variables. There are even more secure ways to handle these keys and we suggest you implement and follow good practice.

Edit the Karbon API 3.0 collection and add a Bearer Token type of Authorization.

Add in the variable

that you created when you added the variable into the Environment.

Make sure to set your baseUrl to be

Now we just need to add the AccessKey to the header:

We've created a preset that is easier to manage, but you can add it to each endpoint if you like.

And then we're good to go! We've just used the Contacts endpoint with the GET method and removed all the parameters.

3. Happy coding!

The Karbon public API requires two separate HTTP headers to be set in order to authenticate a request: Authorization and AccessKey (note the US spelling of Authorization).

If there is a problem with the authentication details you’ve provided with your API request, the API server will respond with a response code of 401 and an error message like Unauthorized. Auth token is missing or invalid.

Below you'll find some common reasons for authentication problems, along with things you can check that may help you successfully authenticate your request.

Many API users that hit authentication issues have accidentally swapped the values that are assigned to the Authorization and AccessKey headers.

Authorization uses the shorter of the two values (Application ID) and should be prefixed with the word Bearer - a correct value will look similar to Bearer 2ff0e384-556e-4431-bac1-2177fb27d94d

AccessKey uses the longer of the two values and is a JWT format, this value will start with the letters eyJ a correct value will look similar to eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJLYXJib25IUSIsInJlZyI6IkhpIHRoZXJlISIsInRhayI6IjU3Mzc0MDRDLTQ0QjgtNDJDRS04MUY2LTAwNTVENzJBRTFBOCIsImlhdCI6MTc0ODM4NzQ1N30.xXQy4XDzSuavFOTQgtmcWY_Tbxe3WU4aeCF4zIlk0ga

Note that the Application ID and AccessKey shown above are just examples and will not allow you to authenticate your request.

Similar to the scenario above, but one or both of the values are missing entirely.

The error message can be used to track down which field is the problem -

Some integration tools may automatically add the Bearer prefix before the Application ID - to see if this is your issue you can try removing the Bearer prefix from the value you send in the Authorization header.

There are some endpoints that are not available to all API users - in this case you’ll see a 401 response code and either no error message or an error message that explains the specific access limitation being applied.