API

If you want to program your own integration, here you will find the basic necessary information.

Basic Information

Costlocker currently offers 2 APIs - REST and GraphQL.

REST API

The original Costlocker API, whose operation will be terminated on March 31, 2025.

You can find the original documentation on Apiary 🔗.

GraphQL

Costlocker now uses the GraphQL API, which powers our Frontend - you can use it to perform anything available in the user interface.

Authorization

The GraphQL API utilizes two methods of authorization:

API Token

The basic form uses the Personal API Token for authorization. To authorize, you need to use the following header:

Authorization: Static ${PERSONAL_API_TOKEN}

JWT Token

The second option uses a JWT Token, generated by the backend upon login (mutation Login). It uses a set of two headers:

Authorization: JWT ${JWT_TOKEN}
Person-Id: ${personId}

With the JWT Token, the Person-Id header is also used because Costlocker is a multi-tenant platform, allowing you to have multiple accounts under a single login. The Person ID is the ID from the People module (visible in the URL parameter).

Deprecation and Warning Handling

The GraphQL API does not use versioning but instead marks individual queries/mutations or fields as deprecated and subsequently removes them.

To monitor these changes, we recommend implementing warning logging into a logging tool, such as Sentry 🔗.

All responses from the Costlocker API may include Extensions 🔗 with a warnings attribute.

Warnings then contain information about the deprecation of the queries/mutations or their fields you are using:

{
    “data”: …,
    “error”: …,
    “extras”: null | {
        “warnings”: null | string
    }
}

Deprecation information is formatted as follows:

DEPRECATED: Field ${FIELD_NAME} is deprecated: ${DEPRECATION_DETAILS}

For example:

DEPRECATED: Field revenue_loss is deprecated: Use field metrics.revenue_loss instead. Will be removed on 03/31/2025.