---
title: How to securely authenticate to platform APIs from playbooks using a personal access token
slug: troubleshooting/how-to-securely-authenticate-to-platform-apis-from-playbooks-using-a-personal-access-token
createdAt: 2026-11-18T13:44:04.355Z
---

## Purpose

This article describes how to call Tenant, Swimlane, and Turbine APIs from playbooks using a personal access token (PAT) without storing credentials in playbook configuration. Use it when playbook automation needs authenticated HTTP access to the platform.

***

## Core rule: send PAT as `Private-Token`, not Bearer

Turbine PATs must be sent as:

```text
Private-Token: <YOUR_PAT>
```

The HTTP Request action’s Bearer Token option sends `Authorization: Bearer <token>`. For Turbine platform APIs, that path validates a login JWT, not a PAT. A PAT in Bearer auth usually returns 401 with `"Token validation failed"`.

| Setup                                                                                        | Secure?                                           | Works with Turbine PAT? |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------- |
| PAT in an asset (HTTP API Key header `Private-Token`, or Swimlane Turbine API connector PAT) | Yes — recommended                                 | Yes                     |
| HTTP Request Bearer Token                                                                    | No                                                | No                      |
| PAT in playbook Authentication, Headers, or inputs                                           | No — exposes secrets in config, exports, and runs | Do not use              |

***

## Step 1: Create a personal access token

1. Sign in to Turbine.
2. Open **Profile & user settings**.
3. Open **Personal Access Token**.
4. Click **Generate Token**.
5. Copy the token immediately; it will not be shown again.

Security practices:

- Use a service account with the minimum roles required.
- Rotate the PAT by updating the asset only, not playbook steps.
- Never share PATs in tickets, chat, or source control.

Knowledge Center: [Creating a Personal Access Token](https://docs.swimlane.com/turbine-user-guide/customize-your-user-profile#creating-a-personal-access-token)

***

## Recommended approach 1: HTTP Request native action + asset

Use this when you need the full URL (Tenant API, Swimlane API, Turbine API, or other paths).

### 1. Create the PAT asset

1. Go to **ORCHESTRATION → Assets**.
2. Create an asset using **API Key** authentication (same pattern as the [HTTP connector](https://docs.swimlane.com/connectors/http)):
   - **API Key Name:** `Private-Token`
   - **API Key Value:** service account PAT
   - **API Key Location:** Header
3. Save the asset.

Knowledge Center: [Assets](https://docs.swimlane.com/turbine-user-guide/assets)

![](https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/RFt3C4Yp7LCdMNXIFKBsU_image.png)

### 2. Attach the asset on the HTTP Request action

1. Add an **HTTP Request** native action.
2. Set method and full endpoint URL.
3. Select the PAT asset in the action **Asset** field.
4. Do not store the PAT in Authentication, Headers, or playbook inputs.

Knowledge Center: [Using the HTTP Request Native Action](https://docs.swimlane.com/turbine-user-guide/using-the-http-request-native-action)

![](https://api.archbee.com/api/optimize/n8uUzk0MM4uC57-zlHNtY/G48NDTJ9npX7Lp1qD38uM_image.png)

### 3. Optional: verify with a GET

Example read-only check:

- `GET` `https://<host>/tenant/api/accounts/<ACCOUNT_ID>/users/light`
- Optional query: `size` = `20`, `pageNumber` = `1` (integers only)
- Expect HTTP 200 when the asset and path are correct.

***

## Recommended approach 2: Swimlane Turbine API connector + PAT asset

Use this for Turbine orchestration API calls through the supported connector instead of hand-building every HTTP Request.

### 1. Configure the connector asset

1. Go to **ORCHESTRATION → Assets**.
2. Create a **Swimlane Turbine API** asset.
3. Configure **PAT authentication** (instance URL + PAT). Prefer PAT over username/password in the asset when possible.
4. Save the asset.

Knowledge Center: [Swimlane Turbine API connector — Configurations](https://docs.swimlane.com/connectors/swimlane-turbine-api) (Turbine API Authentication and PAT Authentication)

### 2. Run Generic Turbine API Request

1. Add the **Generic Turbine API Request** action from the Swimlane Turbine API connector.
2. Select the PAT asset.
3. Set `host` (for example `sg1.swimlane.app`), `path`, and `method` per the connector documentation.

Knowledge Center: [Generic Turbine API Request](https://docs.swimlane.com/connectors/swimlane-turbine-api) (inputs: `host`, `path`, `method`)

| Need                                                         | Use                                                     |
| ------------------------------------------------------------ | ------------------------------------------------------- |
| Tenant API (`/tenant/api/...`), Swimlane API, arbitrary URLs | Approach 1 — HTTP Request + PAT asset                   |
| Turbine orchestration API via the connector                  | Approach 2 — Swimlane Turbine API connector + PAT asset |

***

## API path patterns

| API surface  | Path pattern                                                                    |
| ------------ | ------------------------------------------------------------------------------- |
| Tenant API   | `https://<host>/tenant/api/accounts/{accountId}/...`                            |
| Swimlane API | `https://<host>/api/account/{accountId}/tenant/{tenantId}/...`                  |
| Turbine API  | `https://<host>/orchestration/api/account/{accountId}/tenant/{tenantId}/v1/...` |

**Common mistakes**: singular `/tenant/api/account/...` (404); missing `Private-Token` (401); PAT sent as Bearer (401).

Knowledge Center: [Audit Logging](https://docs.swimlane.com/audit-logging) (example curl with `Private-Token`)

***

## Approaches to avoid (credential exposure)

Do not use these patterns, even if they appear to work:

- Entering the PAT on the HTTP Request **Authentication** tab without an asset.
- Literal `Private-Token` in the **Headers** tab.
- PAT in playbook properties, variables, or action inputs.
- Username and password typed on actions instead of a secured asset.
- **Bearer Token** on HTTP Request for a Turbine PAT.

If a PAT was stored in a playbook, rotate the PAT and move credentials to an asset.

***

## Troubleshooting

| Symptom                         | Likely cause             | What to do                            |
| ------------------------------- | ------------------------ | ------------------------------------- |
| 401 `"Token validation failed"` | PAT sent as Bearer       | Use PAT asset; `Private-Token` header |
| 401 (other)                     | Invalid or revoked PAT   | Regenerate PAT; update asset          |
| 403                             | Insufficient roles       | Adjust service account                |
| 404                             | Wrong URL                | Use `accounts` (plural); verify host  |
| 400 on `size` / `pageNumber`    | Non-integer query values | Use numbers or omit params            |
| Token in export or run          | PAT not in asset         | Move to asset; rotate PAT             |

***

## Security checklist

- Service account PAT with least privilege
- PAT stored only in assets (HTTP API Key or Swimlane Turbine API connector)
- No literal tokens in HTTP Request fields
- SSL verification enabled in production
- PAT rotated after exposure or personnel change

***

## Related documentation (Knowledge Center)

| Topic                                                  | Link                                                                                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Create PAT                                             | [Customize Your User Profile](https://docs.swimlane.com/turbine-user-guide/customize-your-user-profile)                   |
| HTTP Request native action                             | [Using the HTTP Request Native Action](https://docs.swimlane.com/turbine-user-guide/using-the-http-request-native-action) |
| Assets                                                 | [Assets](https://docs.swimlane.com/turbine-user-guide/assets)                                                             |
| API Key asset pattern                                  | [HTTP connector](https://docs.swimlane.com/connectors/http)                                                               |
| Swimlane Turbine API connector (PAT + Generic Request) | [Swimlane Turbine API connector](https://docs.swimlane.com/connectors/swimlane-turbine-api)                               |
| `Private-Token` curl example                           | [Audit Logging](https://docs.swimlane.com/audit-logging)                                                                  |

