Authentication

Every request to https://api.botsi.com carries one of your app's API keys in the Authorization header. Find the secret key on the App configuration page in the dashboard at https://app.botsi.com.

A server-to-server call sends the secret key:

Authorization: {{secret_key}}
Content-Type: application/json

A call made from inside an app sends the public key in that same header:

Authorization: {{public_key}}

Send the key raw, with no scheme prefix

There is no Bearer and no Api-Key prefix. The header value is the key itself.

Adding a prefix is the most common cause of an authentication failure that looks like a wrong key.

Choosing a key#

Either key works on the V2 routes an app calls: profiles, custom attributes, paywall, events, purchases, Apple promotional offers, and Apple Search Ads attribution. Use the secret key for server-to-server calls. The public key is for calls made from inside an app. It ships in the app binary, and the iOS SDK 2.0 sends it on these routes. Delete a Profile is the exception among those profile routes and accepts the secret key only.

Never put the secret key in a mobile or web client

Anyone who unpacks your app binary or reads your page source can read a key shipped there. Keep the secret key on your servers.

POST /v2/transactions and DELETE /v2/profiles/{profileId} accept only the secret key. A public key is rejected with 401. See Delete a Profile.

The examples across these docs send $BOTSI_SECRET_KEY. From inside an app, send $BOTSI_PUBLIC_KEY in that same header.

Making an example authenticated request#

# Authorization: $BOTSI_SECRET_KEY or $BOTSI_PUBLIC_KEY
curl -X POST "https://api.botsi.com/v2/events" \
  -H "Authorization: $BOTSI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "paywall_shown",
    "paywallSessionId": "v1.eyJhIjo0MDIxLCJ3Ijo5MDUsInAiOiJvbmJvYXJkaW5nIiwiaSI6MTc4NTMxMjAwMH0.QmzR1w"
  }'

Troubleshooting#

A 401 Unauthorized means no valid key was provided. Check the key matches your App configuration page exactly, and that no scheme prefix was added. The response body is:

{ "error": "No valid API key provided.", "code": "unauthorized" }

A 403 Forbidden means the key is valid but lacks permission for that resource.