Getting Started

This guide shows how to get an access token and make your first call to the Kalepa API.

The base URL for production is https://api.kalepa.com. All examples on this page use it.

Before you start

Kalepa gives you two values for your API client:

Value	Placeholder in this guide
Client ID	`<client_id>`
Client secret	`<client_secret>`

Keep the client secret private. Do not put it in client-side code or in logs.

Step 1: Get an access token

Call POST /external/auth/token. The endpoint uses the OAuth 2.0 Client Credentials grant. Send the body as application/x-www-form-urlencoded.

All four fields are required:

Field	Value
`grant_type`	`client_credentials`
`client_id`	Your client ID
`client_secret`	Your client secret
`audience`	`https://api.kalepa.com`

Put your credentials in shell variables first, so they never appear in the command itself:

export CLIENT_ID="<client_id>"
export CLIENT_SECRET="<client_secret>"

curl -X POST "https://api.kalepa.com/external/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=${CLIENT_ID}" \
  --data-urlencode "client_secret=${CLIENT_SECRET}" \
  --data-urlencode "audience=https://api.kalepa.com"

Example response (200 OK):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "<granted scopes>",
  "expires_in": 86400,
  "token_type": "Bearer"
}

The response fields:

Field	Meaning
`access_token`	A JSON Web Token. Send it as a Bearer token on every authenticated endpoint.
`scope`	The scopes granted to your client.
`expires_in`	The number of seconds the token is valid. The value above is an example.
`token_type`	Always `Bearer`.

A 400 response means the request is invalid. Common causes are a missing field or wrong client credentials. The response body includes an error field with a description of the problem.

Step 2: Store the token

Store the token in a shell variable. The other guides use $TOKEN in every example.

export TOKEN=$(curl -s -X POST "https://api.kalepa.com/external/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=${CLIENT_ID}" \
  --data-urlencode "client_secret=${CLIENT_SECRET}" \
  --data-urlencode "audience=https://api.kalepa.com" | jq -r '.access_token')

This command needs jq. If you do not have jq, copy the access_token value from the response by hand.

Step 3: Make an authenticated call

Send the token in the Authorization header on every authenticated call:

Authorization: Bearer <access_token>

Example: read one report by its Kalepa report ID.

curl "https://api.kalepa.com/external/reports/f116fa5c-e5d9-43c2-8dc3-ac3fa60ff3b3" \
  -H "Authorization: Bearer $TOKEN"

Example response (200 OK):

{
  "id": "f116fa5c-e5d9-43c2-8dc3-ac3fa60ff3b3",
  "name": "Acme Manufacturing, Inc.",
  "status": "Quoted"
}

A 401 response means the token is missing, expired, or invalid. Request a new token and retry.

Token lifetime

Use one token for many calls. Do not request a new token for every call.
Request a new token when expires_in seconds have passed, or when a call returns 401.
If you request a token again before the current one expires, the API can return the same cached token. In that case expires_in shows the remaining lifetime, not the full lifetime.

Next steps

Work with reports: create, read, update, and find reports.
Work with report files: upload, list, update, and delete the files of a report.
Work with client data: send field values from your own system onto a report.
The API reference lists every endpoint, field, and response.