Guides
API Reference

👥 User Provisioning

Provision and deprovision users in your Pine AI whitelabel organization via API

User Provisioning

The provision user endpoint lets you programmatically add and remove users from your Pine AI whitelabel organization.

Prerequisites

Before provisioning users, ensure:

  1. Auth0 organization is configured — Set up authentication in the dashboard. Your Auth0 organization must be created before you can provision users.
  2. Free access is disabled — The freeAccess setting must be false. When free access is enabled, all users can access the chat without provisioning, and the provisioning endpoint is disabled.

Provisioning a User

Send a POST request to create a new user in your Auth0 organization. The user will receive a password reset email and be redirected to your result_url after setting their password.

You can optionally set per-user monthly chat limits at provision time via the pro_monthly_chat_limit and lite_monthly_chat_limit fields. When omitted, users inherit the partner-level flat limits configured in your dashboard.

cURL

curl -X POST https://api.sharpsports.io/v1/pine/partner/provision-user \
  -H "Authorization: Token YOUR_PRIVATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "provision",
    "email": "[email protected]",
    "result_url": "https://chat.yoursite.com"
  }'

With per-user chat limit overrides

curl -X POST https://api.sharpsports.io/v1/pine/partner/provision-user \
  -H "Authorization: Token YOUR_PRIVATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "provision",
    "email": "[email protected]",
    "result_url": "https://chat.yoursite.com",
    "pro_monthly_chat_limit": 250,
    "lite_monthly_chat_limit": 100
  }'

Python

import requests

response = requests.post(
    "https://api.sharpsports.io/v1/pine/partner/provision-user",
    headers={
        "Authorization": "Token YOUR_PRIVATE_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "action": "provision",
        "email": "[email protected]",
        "result_url": "https://chat.yoursite.com",
        # Optional: per-user chat limit overrides
        "pro_monthly_chat_limit": 250,
        "lite_monthly_chat_limit": 100
    }
)

print(response.json())

Parameters

FieldTypeRequiredDescription
actionstringNo"provision" (default), "deprovision", or "update_limits"
emailstringYesThe user's email address
result_urlstringYes (provision only)URL the user is redirected to after setting their password
pro_monthly_chat_limitintegerNoPer-user override for monthly Pro chat limit. Omit to inherit your partner-level flat limit.
lite_monthly_chat_limitintegerNoPer-user override for monthly Lite chat limit. Omit to inherit your partner-level flat limit.

What Happens

  1. A user account is created in your Auth0 organization
  2. A password reset email is sent to the user
  3. The user clicks the link, sets their password, and is redirected to your result_url
  4. The user can now log in to your whitelabel chat application

Updating Chat Limits

Use the update_limits action to change a user's chat limit overrides without re-provisioning them. This is useful when a user changes tiers (e.g. upgrades from Basic to Premium) and you want to adjust their caps.

This action only updates limit fields — it does not touch Auth0, entitlements, or subscription state, and does not require result_url.

cURL

curl -X POST https://api.sharpsports.io/v1/pine/partner/provision-user \
  -H "Authorization: Token YOUR_PRIVATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_limits",
    "email": "[email protected]",
    "pro_monthly_chat_limit": 500,
    "lite_monthly_chat_limit": null
  }'

Python

import requests

response = requests.post(
    "https://api.sharpsports.io/v1/pine/partner/provision-user",
    headers={
        "Authorization": "Token YOUR_PRIVATE_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "action": "update_limits",
        "email": "[email protected]",
        "pro_monthly_chat_limit": 500,
        "lite_monthly_chat_limit": None
    }
)

print(response.json())

Parameters

FieldTypeRequiredDescription
actionstringYesMust be "update_limits"
emailstringYesThe email address of the user to update. Must already be provisioned.
pro_monthly_chat_limitinteger or nullNoSee semantics below
lite_monthly_chat_limitinteger or nullNoSee semantics below

At least one of pro_monthly_chat_limit or lite_monthly_chat_limit must be provided.

Field Semantics

For pro_monthly_chat_limit and lite_monthly_chat_limit, the behavior differs based on what you send:

What you sendEffect
Field omittedNo change — current value preserved
nullOverride cleared — user falls back to your partner-level flat limit
Integer (≥ 0)Override set to that value

How Limits Resolve

When the chat consumer evaluates a partner user's monthly limit, it uses the following precedence:

  1. Per-user override (set via provision or update_limits) — if not null, this wins.
  2. Partner-level flat limit — your dashboard's proMonthlyChatLimit / liteMonthlyChatLimit.
  3. Unlimited — if neither is configured.

Deprovisioning a User

Remove a user from your organization. This revokes their access to your whitelabel chat.

cURL

curl -X POST https://api.sharpsports.io/v1/pine/partner/provision-user \
  -H "Authorization: Token YOUR_PRIVATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "deprovision",
    "email": "[email protected]"
  }'

Python

import requests

response = requests.post(
    "https://api.sharpsports.io/v1/pine/partner/provision-user",
    headers={
        "Authorization": "Token YOUR_PRIVATE_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "action": "deprovision",
        "email": "[email protected]"
    }
)

print(response.json())

Error Codes

CodeCause
400Missing email, missing result_url (for provision), freeAccess is enabled, Auth0 organization not configured, no limit fields provided (for update_limits), or limit value is not a non-negative integer or null
403Sandbox account or insufficient permissions
404Pine whitelabel configuration not found for your account, or user not found (for update_limits)
503Internal service not configured or upstream error

Related

Updated 14 days ago