Access tokens

Your backend needs an access token for every telemetry call. This guide covers how to keep tokens, renew them and protect the credentials behind them.

To get your keys and your first token, see Generate keys and get a token.

What you have

Item	How you use it
Consumer key	Your application's identifier. You send it with HTTP Basic authentication.
Consumer secret	Your application's secret. You send it with HTTP Basic authentication.
Token endpoint	https://apim.kairosinnovations.dev/oauth2/token
Telemetry gateway	https://gw.kairosinnovations.dev/api/v1/ingest/telemetry

The Environments page lists the Integration environment URLs.

Cache and reuse the token

• Keep the token in memory and reuse it. Do not request a new token for every telemetry batch.
• Work out when the token expires from the expires_in value in the token response. It is the lifetime in seconds. Always use the real value, not an example.
• Renew the token about 60 seconds before it expires.

In outline, your backend does this:

consumer_key    = secret_manager.get("IFMS_CONSUMER_KEY")
consumer_secret = secret_manager.get("IFMS_CONSUMER_SECRET")

response = HTTP POST https://apim.kairosinnovations.dev/oauth2/token
           Basic Auth key    = consumer_key
           Basic Auth secret = consumer_secret
           Form grant_type   = client_credentials

cache response.access_token until 60 seconds before response.expires_in

The Python, JavaScript and Java sample clients all cache the token this way.

There is no refresh token

The client credentials grant does not use a refresh token. To renew, repeat the same token request.

When the gateway returns 401

1. Get a new token.
2. Retry the telemetry request once.
3. If the retry also returns 401, stop retrying. Contact your IFMS integration coordinator.

Troubleshooting and FAQ lists what else to check.

Keep TLS verification on

• Never add cURL's -k option, and never turn off certificate checks in your HTTP library.
• A certificate error must be investigated, not bypassed.

Protect your credentials

The consumer secret is a long-lived credential.

• Load the consumer key and secret from a protected secret manager or protected environment variables.
• Never put the secret in source code, telemetry JSON, screenshots, logs, email or support tickets.
• Send the key and secret only to the token endpoint. Never send them to the telemetry gateway.
• Treat the access token as sensitive too. Do not decode it or log it.

With cURL, --user "$IFMS_CLIENT_ID" makes cURL prompt for the secret, so it is not shown while you type. IFMS_CLIENT_ID holds your consumer key, as in the sample code. The --user option builds the HTTP Basic Authorization header for you. If a technical note shows Base64(consumer-key:consumer-secret), it explains that header: it is not text to paste.

Test with Postman

1. Create a request with the method POST and the URL https://apim.kairosinnovations.dev/oauth2/token.
2. Open Authorization and select Basic Auth. Enter the consumer key in the first credential field and the consumer secret in the second.
3. Open Body and select x-www-form-urlencoded. Add the key grant_type with the value client_credentials.
4. Select Send. A successful response is HTTP 200 and contains access_token, token_type and expires_in.

In a shared Postman workspace, keep the consumer secret in Postman Vault or in an unsynchronised local value. Never save it in a shared collection, environment, example response or screenshot.

Rotate credentials

When IFMS issues replacement credentials:

1. Update the credentials in your secret store.
2. Get a new token with the new credentials.
3. Send a telemetry request through the gateway and check that it works.
4. Remove the old credentials as IFMS instructs.

Do not rotate credentials automatically when the token endpoint or the gateway returns a 5xx error. Those errors are temporary: retry with backoff instead.