API authentication

This page covers the two credentials you use with Outrun: workspace API keys for the Outrun API, and source tokens for the website chat widget. It is for developers connecting their own systems to an Outrun workspace.

Workspace API keys

Use a workspace API key for programmatic access to your workspace through the Outrun GraphQL API.

Create a key

1. In your workspace, open Settings > API Keys.
2. Select Create API Key.
3. Enter a Key Name and select the Permissions the key needs.
4. Copy the key and store it as you would a password.

You can edit or delete a key from the same page. Deleting a key stops every request that uses it.

Send the key

Send the key in the Authorization header with the Bearer scheme:

curl -X POST https://api.getoutrun.com/graphql \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}'

The API accepts the key only in the Authorization header. It does not read keys from query parameters or other headers.

Errors

Authentication errors return HTTP 401. Except for a missing header, the body is a problem object (RFC 9457); read its error_code field to decide what to do.

Example response for an unknown key:

{"type":"https://docs.getoutrun.com/errors/auth","title":"Invalid API key","status":401,"detail":"The provided API key is not valid or has been revoked.","error_code":"AUTH_INVALID_KEY","error_category":"auth","retryable":false,"retry_after":null,"owner_action_required":false,"timestamp":"2026-10-17T05:20:05.528Z"}

For problem objects, send Accept: application/problem+json to receive the application/problem+json content type, or Accept: text/markdown to receive the same error as Markdown.

Rate limits

Requests are counted per API key. Requests without a key are counted per client IP address. Above the limit the API returns HTTP 429 with a Retry-After: 60 header. Wait 60 seconds before you retry.

Chat widget credentials

The website chat widget does not use a workspace API key. It uses credentials that belong to a website source.

Source token

When you add a website source, Outrun shows its Bearer Token once on the Add Website screen. Copy it before you leave the screen.

The widget sends this token with each chat request. A missing or wrong token returns HTTP 401 with {"error":"Invalid or missing bearer token"}.

The widget script is served from https://cdn.getoutrun.com/sdk/outrun.min.js. For installation steps, see the chat widget guide.

Allowed domains

You list the Allowed Domains for a website source when you add it. Chat requests from a page whose domain is not on the list return HTTP 403 with {"error":"Origin not allowed for this source"}.

• example.com allows only that domain.
• *.example.com allows example.com and all of its subdomains.

Identity verification

Visitor details sent from the browser are self-reported. To prove which of your users a visitor is, sign their user ID on your server and pass the signature to the widget.

1. On your server, compute the hex-encoded HMAC-SHA256 of the user's ID, using the website source's identity secret as the key. The Outrun app does not display the identity secret.
2. Pass the user ID as externalId and the signature as externalIdSignature when you start the chat widget.

// Node.js, on your server
const crypto = require('crypto');

const externalIdSignature = crypto
  .createHmac('sha256', identitySecret) // load from your server's secret store
  .update('user-123')
  .digest('hex');

If the signature matches, Outrun treats the visitor as verified. If it does not match, the message is still delivered and the visitor is treated as unverified.

The same rule applies to outrun.identify: it links a visitor to a known person only when the user ID carries a valid signature. Without one, it only records traits for that browser.

Outrun has no signing endpoint. Always compute the signature on your own server.

Keep the identity secret on your server. Never send it to the browser.