Authentication

All API requests to Incremental are authenticated. To authenticate, your API token must be incorporated into the header of the request as a bearer token. There are two ways to obtain one.

Request headers

Every GraphQL request must include the following headers:

Header	Optional	Value
Content-Type	mandatory	application/json
Authorization	mandatory	Bearer <API_TOKEN>

Account scoped API keys

Account scoped API keys are able to be generated by admins within each account. For security reasons these are scoped to the individual account and can be used for custom or unique use cases that fall within the platform TOS. Each API key grants access to specific data based on the associated permissions.

Account scoped API keys are able to be used directly as exemplified in the headers table above. Pass the token directly as a bearer token:

curl https://api.incremental.com/graphql \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

Tokens can be created and managed via the createAPIToken mutation and listed with listAPITokensByCompany. The token value is only returned once, at creation time.

Preferred partner tokens

Specific partners that work across multiple Incremental clients may be granted platform tokens that allow access to multiple accounts at once. For these tokens, each Incremental account must opt-in to sharing information with the 3rd party partner. Similar to account scoped tokens, preferred partner tokens must adhere to platform TOS.

Preferred partners utilize a client credential grant OAuth 2.0 flow, thus requiring extra steps to receive a usable token. As part of your API onboarding, you will be securely sent credentials which contain a client_id and a client_secret. To exchange these credentials for a token, make the following request:

curl --request POST --url 'https://login.incremental.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data audience=https://api.tradeswell.com/

The response contains the access token, its lifetime in seconds, and the token type:

{
  "access_token": "eyJz93a...k4laUWw",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Use access_token as the bearer token exactly as with an account-scoped key.

Cache your tokens

A new token should not be generated for each request. Instead, the token should be cached with a TTL defined by the expires_in property, represented in seconds — see Best practices.