Authentication

Overview

The SiteAssist API uses two authentication methods depending on the endpoint and use case:

1. API Key Authentication - For initializing sessions and public operations
2. Bearer Token Authentication - For authenticated requests after session initialization

API Key Authentication

API keys are used to identify your project and initialize visitor sessions. They are passed directly in the request body or as query parameters.

Using Publishable Keys

Publishable keys (pk_*) are used in client-side applications to initialize visitor sessions:

// Initialize a visitor session with your publishable key
const response = await fetch('https://api.siteassist.io/v2/identity/init', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    apiKey: 'pk_your_publishable_key_here',
    saVid: 'unique-device-id-123',
  }),
});

Using Private Keys

Private keys (sk_*) provide full access to the API and should only be used server-side. They are typically used as Bearer tokens:

// Using private key as Bearer token (server-side only)
const response = await fetch('https://api.siteassist.io/v2/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_your_private_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: 'Hi'
      }
    ]
  })
});

Caution

Never expose private keys in client-side code! Private keys should only be used in secure server environments.

Bearer Token Authentication

After initializing a visitor session, you receive a short-lived session token that must be used for subsequent authenticated requests.

Session Token Lifecycle

1. Initialize: Call /identity/init with your publishable API key
2. Receive: Get a sessionToken in the response
3. Use: Include the token in the Authorization header for subsequent requests
4. Expire: Session tokens are short-lived and expire after a period of inactivity

Example: Complete Authentication Flow

// Step 1: Initialize visitor session
const initResponse = await fetch('https://api.siteassist.io/v2/identity/init', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    apiKey: 'pk_your_publishable_key_here',
    saVid: 'device-abc-123',
  }),
});

const { sessionToken, visitor } = await initResponse.json();

// Step 2: Use session token for authenticated requests
const conversationResponse = await fetch('https://api.siteassist.io/v2/conversations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    context: {
      pageUrl: 'https://example.com/support',
    },
  }),
});

const conversation = await conversationResponse.json();

// Step 3: Continue using the same session token
// for all requests in this session
console.log('Visitor ID:', visitor.id);
console.log('Conversation ID:', conversation.id);

Authentication by Endpoint

Different endpoints use different authentication methods:

Endpoint	Authentication Method	Key Type
POST /identity/init	API Key (in body)	Publishable
GET /identity/me	Bearer Token	Session Token
GET /projects/current	API Key (query param)	Publishable
POST /conversations	Bearer Token	Session Token
GET /conversations	Bearer Token	Session Token
POST /conversations/{id}/messages	Bearer Token	Session Token
GET /projects/{id}/qnas	No auth required	-
GET /search	API Key (query param)	Publishable
POST /chat/completions	Bearer Token	Private

Note

Session Tokens vs Private Keys: While both can be used as Bearer tokens, session tokens are for visitor-scoped operations (conversations, messages), while private keys provide full project access.

Error Responses

When authentication fails, the API returns appropriate error responses:

401 Unauthorized

The authentication token is missing or invalid:

{
  "error": {
    "message": "Authentication required",
    "code": "UNAUTHORIZED"
  }
}

Common causes:

• Missing Authorization header
• Expired session token
• Invalid or revoked API key
• Malformed Bearer token

403 Forbidden

The authenticated user doesn’t have permission to access the resource:

{
  "error": {
    "message": "Access denied to this conversation",
    "code": "FORBIDDEN"
  }
}

Common causes:

• Trying to access another visitor’s conversation
• Using a publishable key for admin operations
• Domain restrictions on publishable key

Best Practices

Security

1. Store Keys Securely: Use environment variables, never hardcode keys
2. Rotate Keys Regularly: Create new keys and revoke old ones periodically
3. Use HTTPS Only: Never send API keys over unencrypted connections
4. Implement Key Rotation: Have a process to update keys without downtime

# Good: Store in environment variables
SITEASSIST_PUBLISHABLE_KEY=pk_abc123...
SITEASSIST_SECRET_KEY=sk_xyz789...

# Never commit these to version control!

Need Help?

We’re here to help you succeed! Whether you have questions, need assistance with setup, or want to discuss advanced use cases, our team is ready to provide personalized support.

Contact us: support@siteassist.io

We’d love to hear about your use case and help you get the most out of SiteAssist!