API Authentication

API Authentication

Outrun uses token-based authentication for all API and SDK interactions. This guide covers how to get your credentials, authenticate requests, and verify visitor identities.

Authentication Methods

Bearer Token

The primary authentication method for Outrun APIs. Include your token in the Authorization header of every request:

Authorization: Bearer your-token-here

Bearer tokens are scoped to a specific source (data connection) within your workspace. Each source has its own token, so you can grant and revoke access per integration.

API Key

For server-to-server integrations, you can use an API key passed as a query parameter or header. API keys provide the same access as bearer tokens but are designed for backend services where header-based auth is less convenient.

X-API-Key: your-api-key-here

Getting Your Credentials

1. Log in to your Outrun workspace at app.getoutrun.com
2. Navigate to Settings > Sources
3. Select the source you want to authenticate with (or create a new one)
4. Copy the Bearer Token shown on the source configuration page

SDK Authentication

The Outrun chat widget SDK authenticates using your source's bearer token. The SDK connects to your workspace automatically based on your domain configuration, so the token is validated server-side on every message.

Basic SDK Setup

The SDK script loads from our CDN and connects to your workspace without exposing API keys in client-side code:

<script src="https://cdn.getoutrun.com/sdk/outrun.min.js" async></script>

The SDK validates your domain against the source's allowed origins list. Requests from unauthorized domains are rejected with a 403 error.

Identity Verification (HMAC)

By default, visitor data passed via Outrun.identify() is self-reported by the browser and cannot be trusted for sensitive operations. Identity verification uses HMAC-SHA256 to prove that the visitor's ID was signed by your backend.

When you need identity verification:

• Your agents perform actions on behalf of the user (account changes, purchases)
• You need to prevent visitors from impersonating other users in chat
• You want to ensure your agents can trust the visitor's identity for personalised responses

How it works:

1. Your backend signs the user's external ID with your source's Identity Secret
2. The SDK sends both the external ID and the signature with each message
3. Outrun verifies the signature server-side using timing-safe comparison
4. If verification passes, the visitor is marked as identity-verified

For the full implementation guide including backend signing code, see the Chat Widget & SDK documentation.

Domain Validation

All SDK requests are validated against the source's configured allowed origins. This prevents unauthorized websites from using your source token. Configure your allowed domains in the source settings page.

Requests with an origin that does not match the allowed list receive a 403 Origin not allowed error.

Security Best Practices

Error Responses

If you receive authentication errors, verify that:

1. Your token matches the one shown in your source settings
2. The Authorization header is formatted correctly (Bearer followed by the token, with a space)
3. Your domain is listed in the source's allowed origins (for SDK requests)