Custom Authorization Setup

Configure automatic token fetching, placeholder injection, and refresh token flows for your APIs — no tokens ever exposed to end users.

How it works

  1. Widget initialises and sends user info to StrikeUp

  2. StrikeUp calls your token endpoint with configured headers / body

  3. StrikeUp extracts the token from the response using your configured path

  4. The token is encrypted and stored — never visible client-side

  5. Every API call automatically carries the token in the configured header

  6. On 401, StrikeUp silently refreshes the token and retries — once

Authorization Types

None

No authorization headers are sent. Use for public APIs.

Static Headers

Fixed headers applied to every request. API key goes here — stored once, injected automatically.

{"Authorization": "Bearer sk-prod-abc123", "X-Api-Key": "key"}
{"Authorization": "Bearer sk-prod-abc123", "X-Api-Key": "key"}
{"Authorization": "Bearer sk-prod-abc123", "X-Api-Key": "key"}

Dynamic Headers

End users provide their own credentials (e.g. their personal API key). StrikeUp prompts them once and stores their input securely.

{"Authorization": "Bearer {user_token}"}
{"Authorization": "Bearer {user_token}"}
{"Authorization": "Bearer {user_token}"}

Custom Auth Endpoint

StrikeUp calls your token endpoint automatically. No user input required (unless you add custom placeholders). Best for OAuth-style flows where the token must be fetched server-side.

Custom Auth Endpoint — Full Setup

Step-by-step configuration for automatic token fetching.

Step 1 — Token Endpoint

Provide the URL StrikeUp will call to obtain an access token. Choose the HTTP method your endpoint requires (POST is most common).

POST https://api.yourcompany.com/auth/token
POST https://api.yourcompany.com/auth/token
POST https://api.yourcompany.com/auth/token

Step 2 — Request Headers

Add any headers your token endpoint requires. Use the {secret} placeholder — it will be replaced with the encrypted secret value you configure below.

Header name:  X-Api-Secret
Header value: {secret}
Header name:  X-Api-Secret
Header value: {secret}
Header name:  X-Api-Secret
Header value: {secret}

Step 3 — Request Body

Configure the JSON body sent with the token request. Built-in placeholders:

Placeholder / setting

Value / description

{secret}

Your encrypted secret value

{userId}

The end user’s ID

{companyId}

Your company / tenant ID

{myPlaceholder}

Any custom placeholder you define

{
  "client_id":     "{secret}",
  "user_id":       "{userId}",
  "tenant_id":     "{companyId}"
}
{
  "client_id":     "{secret}",
  "user_id":       "{userId}",
  "tenant_id":     "{companyId}"
}
{
  "client_id":     "{secret}",
  "user_id":       "{userId}",
  "tenant_id":     "{companyId}"
}

Step 4 — Custom Placeholders (optional)

If your token request needs per-user values that StrikeUp doesn’t know (e.g. a tenant slug or environment name), add custom placeholders. Users will be prompted for these values once, and StrikeUp stores their answers securely.

Example — two custom placeholders:

Key

Label shown to user

tenantId

Your Tenant ID

environment

Environment (prod / staging)

Use them in the body with curly braces:

{
  "tenant_id":   "{tenantId}",
  "environment": "{environment}"
}
{
  "tenant_id":   "{tenantId}",
  "environment": "{environment}"
}
{
  "tenant_id":   "{tenantId}",
  "environment": "{environment}"
}

Step 5 — Response Path

Paste a sample response from your token endpoint and click the field containing the access token — or type the dot-notation path directly.

// Sample response
{
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "dGhpcyBp...",
    "expires_in": 3600
  }
}

// Path to access token → data.access_token
// Sample response
{
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "dGhpcyBp...",
    "expires_in": 3600
  }
}

// Path to access token → data.access_token
// Sample response
{
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "dGhpcyBp...",
    "expires_in": 3600
  }
}

// Path to access token → data.access_token

Step 6 — Authorization Header

Configure how the extracted token is sent with every API call.

Placeholder / setting

Value / description

Header name

Authorization

Header format

Bearer {token}

{token} is replaced with the extracted value at request time.

Refresh Token Configuration

Enable automatic token refresh so expired access tokens are renewed silently — no user disruption, no failed requests.

When a tool call returns HTTP 401, StrikeUp automatically calls your refresh endpoint, stores the new access token, and retries the original request — once.

Refresh Token Path

The dot-notation path to extract the refresh token from the initial auth response. StrikeUp stores this token securely — it is never exposed to the client.

refresh_token        // top-level field
data.refresh_token   // nested field
refresh_token        // top-level field
data.refresh_token   // nested field
refresh_token        // top-level field
data.refresh_token   // nested field

Refresh Endpoint

The URL and HTTP method StrikeUp calls when the access token expires. Set request headers and body using these placeholders:

Placeholder / setting

Value / description

{refresh_token}

The stored refresh token

{secret}

Your encrypted secret

{userId}

The end user’s ID

{companyId}

Your company / tenant ID

POST https://api.yourcompany.com/auth/refresh

// Body
{
  "refresh_token": "{refresh_token}"
}

// Or with extra auth
{
  "refresh_token": "{refresh_token}",
  "client_secret": "{secret}"
}
POST https://api.yourcompany.com/auth/refresh

// Body
{
  "refresh_token": "{refresh_token}"
}

// Or with extra auth
{
  "refresh_token": "{refresh_token}",
  "client_secret": "{secret}"
}
POST https://api.yourcompany.com/auth/refresh

// Body
{
  "refresh_token": "{refresh_token}"
}

// Or with extra auth
{
  "refresh_token": "{refresh_token}",
  "client_secret": "{secret}"
}

New Access Token Path

The dot-notation path to extract the new access token from the refresh response. Leave empty to reuse the main token path. If the refresh response also includes a new refresh token, it is automatically stored (rolling refresh tokens supported).

access_token   // leave empty to reuse main token path
access_token   // leave empty to reuse main token path
access_token   // leave empty to reuse main token path

Complete Example

// ── Token endpoint ──────────────────────────────
POST https://api.example.com/auth/token
Headers: { "x-api-secret": "{secret}" }
Body:    { "user_id": "{userId}" }
Token path:         data.access_token
Header name:        Authorization
Header format:      Bearer {token}

// ── Refresh token ────────────────────────────────
Refresh token path: data.refresh_token   ← extracted on initial fetch

POST https://api.example.com/auth/refresh
Body: { "refresh_token": "{refresh_token}" }
New access token path: data.access_token

// ── On 401 ──────────────────────────────────────
1. StrikeUp detects 401 on a tool call
2. Calls refresh endpoint with stored refresh token
3. Stores new access token (and new refresh token if present)
4. Retries the original tool call once
5. If still 401 → returns error to user
// ── Token endpoint ──────────────────────────────
POST https://api.example.com/auth/token
Headers: { "x-api-secret": "{secret}" }
Body:    { "user_id": "{userId}" }
Token path:         data.access_token
Header name:        Authorization
Header format:      Bearer {token}

// ── Refresh token ────────────────────────────────
Refresh token path: data.refresh_token   ← extracted on initial fetch

POST https://api.example.com/auth/refresh
Body: { "refresh_token": "{refresh_token}" }
New access token path: data.access_token

// ── On 401 ──────────────────────────────────────
1. StrikeUp detects 401 on a tool call
2. Calls refresh endpoint with stored refresh token
3. Stores new access token (and new refresh token if present)
4. Retries the original tool call once
5. If still 401 → returns error to user
// ── Token endpoint ──────────────────────────────
POST https://api.example.com/auth/token
Headers: { "x-api-secret": "{secret}" }
Body:    { "user_id": "{userId}" }
Token path:         data.access_token
Header name:        Authorization
Header format:      Bearer {token}

// ── Refresh token ────────────────────────────────
Refresh token path: data.refresh_token   ← extracted on initial fetch

POST https://api.example.com/auth/refresh
Body: { "refresh_token": "{refresh_token}" }
New access token path: data.access_token

// ── On 401 ──────────────────────────────────────
1. StrikeUp detects 401 on a tool call
2. Calls refresh endpoint with stored refresh token
3. Stores new access token (and new refresh token if present)
4. Retries the original tool call once
5. If still 401 → returns error to user

Injecting Credentials via Embed Code

If your token endpoint requires per-user values (custom placeholders), you can inject them directly from your embed script — so users never see an authorization prompt.

<script src="https://widget.strikeup.io/embed.js"
  data-widget-id="wgt_abc123xyz"
  data-server-authorizations='[
    {
      "serverId": "srv_xyz",
      "authData": {
        "tenantId":    "acme-corp",
        "environment": "production"
      }
    }
  ]'>
</script>
<script src="https://widget.strikeup.io/embed.js"
  data-widget-id="wgt_abc123xyz"
  data-server-authorizations='[
    {
      "serverId": "srv_xyz",
      "authData": {
        "tenantId":    "acme-corp",
        "environment": "production"
      }
    }
  ]'>
</script>
<script src="https://widget.strikeup.io/embed.js"
  data-widget-id="wgt_abc123xyz"
  data-server-authorizations='[
    {
      "serverId": "srv_xyz",
      "authData": {
        "tenantId":    "acme-corp",
        "environment": "production"
      }
    }
  ]'>
</script>

Security note: Only inject non-sensitive values (tenant IDs, environment names) via the embed script. Never inject raw API keys or passwords here — use the Secret field in the admin panel instead, which is encrypted server-side and never exposed to the browser.

Common Issues

❗ Token fetch fails on widget load

  • Wrong endpoint URL or HTTP method

  • Secret value not set or wrong

  • Request headers missing Content-Type

Fix: Check Authorization Logs in the admin panel — the full request and response are recorded.

❗ 401 on every API call (no refresh configured)

  • Access token expired before use

  • Token path is wrong — extracted value is empty

Fix: Paste a sample response into the Response JSON field and use the path selector to pick the correct field.

❗ Refresh token not stored

  • Refresh Token Path not configured

  • Path is wrong — field not found in initial response

Fix: Check the dot-notation path against your actual token endpoint response. Use the path selector.

❗ Refresh succeeds but API still returns 401

  • New token path differs between token and refresh responses

  • Refresh endpoint returns the token under a different key

Fix: Set a dedicated New Access Token Path in the refresh section instead of leaving it empty.

Previous: Setup & Configuration

Next: Authentication Guide