Authentication

Every endpoint except /v1/auth requires a bearer token.

Tokens are issued to a service user provisioned for your integration. It is a machine account: it belongs to your organization, not to any individual, and it is the identity every one of your API calls is attributed to. Treat its credentials as production secrets.

Getting a token

curl -X POST https://partner-api.kricktalk.com/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "••••••••"}'

Send either username + password or refresh_token — never both, and never one half of the credential pair. Any other combination is a 400.

{
  "access_token": "fb79ea2e621bebff9e68ac2a543b1438",
  "refresh_token": "146cd61dc89b7c1fe44dbc9209daac04",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": "9999",
  "domain": "yourpartner.kricktalk"
}

The response carries some additional identity fields. They are not part of this contract — read access_token, refresh_token, and expires_in, and ignore the rest.

Using it

Authorization: Bearer fb79ea2e621bebff9e68ac2a543b1438

Refreshing

expires_in is seconds — one hour today, but read the field rather than hard-coding it. Exchange the refresh token before expiry:

curl -X POST https://partner-api.kricktalk.com/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "146cd61dc89b7c1fe44dbc9209daac04"}'

You get a fresh access_token and a fresh refresh_token. Store the new refresh token — use the one from the most recent response, not the one you started with.

A workable pattern: cache the access token, refresh when it is within a few minutes of expiring, and re-authenticate with the full credentials if a refresh is ever rejected. Refreshing on a timer is better than refreshing on failure, because an expired token is indistinguishable from a revoked one in the response you get back — both are 403. However, re-authenticating on failure is also an option.

Handling 403

A 403 from any endpoint means one of:

• the token is missing, malformed, expired, or revoked;
• your service user lacks the permission that endpoint requires;
• you hold no active integration on the domain named in the request path.

The response does not distinguish between them; it says Forbidden and nothing more. That is deliberate — a more specific message would let an unauthenticated caller probe which domains exist and which integrations are live.

So: on a 403, re-authenticate once. If a request with a freshly-minted token is still refused, the cause is not the token — check that the domain_id in your path is a domain you integrate with, and that the integration is enabled. See Errors and rate limits.

❗️

domain in the token response is your own domain

The token response's domain is the domain your own service user lives in. Endpoints are addressed as /v1/domains/{domain_id}/…, where domain_id is the customer's domain, such as yourcustomer.kricktalk.

They are different domains, and passing your own where a customer's belongs produces a 403 that looks like a permissions problem. Get domain_id values from KrickTalk when your integration on a customer is set up — never from the token response.