Authentication

Tikk supports two kinds of credentials. Both are sent the same way, as a Bearer token, and both are limited by scopes.

Credential	Use it for
OAuth access token	Integrations used by many Tikk users. This is what partners use.
API key (`tikk_sk_…`)	A Tikk user scripting against their own account. Created in Tikk under Settings → API keys.

The rest of this page covers OAuth.

1. Redirect the user to Tikk

Send the user's browser to the authorize endpoint:

https://app.tikk.chat/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.example/callback
  &response_type=code
  &scope=profile.read availability.read
  &state=RANDOM_STRING

Parameter	Required	Notes
`client_id`	yes	From your app's page in My apps.
`redirect_uri`	yes	Must exactly match one of your app's redirect URIs.
`response_type`	yes	Always `code`.
`scope`	no	Space-separated. Defaults to `profile.read`. Scopes your app is not allowed to use are dropped.
`state`	recommended	A random value you check on the way back, to protect against CSRF.

The user signs in to Tikk (if needed), sees your app's name, your company name and the requested permissions, and approves or denies.

2. Handle the callback

On approval, Tikk redirects to your redirect_uri:

https://your-app.example/callback?code=AUTHORIZATION_CODE&state=RANDOM_STRING

If the user denies, you receive error=access_denied instead. Always check that state matches what you sent.

3. Exchange the code for tokens

Make a server-side POST to the token endpoint. Never do this from the browser, because it needs your client secret.

curl -X POST https://app.tikk.chat/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://your-app.example/callback \
  -d code=AUTHORIZATION_CODE

Response:

{
  "token_type": "Bearer",
  "expires_in": 2592000,
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200..."
}

Store both tokens per Tikk user.

4. Refresh the access token

Access tokens last 30 days; refresh tokens last 90 days. Before the access token expires, trade the refresh token for a new pair:

curl -X POST https://app.tikk.chat/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=refresh_token \
  -d refresh_token=REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

Each refresh returns a new refresh token; the old one stops working. If refreshing fails (the user disconnected your app, or the refresh token expired), send the user through the authorize flow again.

Disconnecting

Users can disconnect your app at any time in Tikk under Settings → Connected apps. Their tokens then return 401 and you should show them as disconnected.

Keeping your secret safe

Your client secret is shown once, when you create the app or regenerate the secret. If it leaks, regenerate it on the app's page: the old secret stops working immediately, but existing user tokens keep working.

Authentication

1. Redirect the user to Tikk#

2. Handle the callback#

3. Exchange the code for tokens#

4. Refresh the access token#