Authentication

Every FluidTalk Characters API request is authenticated with a connector token — a single long-lived secret that is one character. There are no account-level keys, no OAuth flows, and no character_id to pass: you send the character's token on every call and FluidTalk resolves it to that exact persona. You name the platform in each request body to select which of the character's bound workflows runs.

This page covers how to create a token, how to send it, why the token is the character, how one token spans all of a character's platforms, how to address multiple accounts on a single platform, and exactly what a missing or bad token returns.

Base URL: https://api-talk.fluidvip.com/api/v1/characters
Dashboard (where tokens are created): https://talk.fluidvip.com

Get a token

Connector tokens are created in the FluidTalk dashboard, not through the public API. (There is no public endpoint to create, list, or rotate tokens — token lifecycle is a dashboard-only, human-in-the-loop operation by design.)

Sign in at https://talk.fluidvip.com.
Open the character (e.g. Ava) and go to its API tab.
Create (or Rotate) the character's connector token. The tab also lets you Delete the token, which revokes API access for the character immediately.
Copy the secret immediately.

The token is shown exactly once. FluidTalk stores only a hash of your token — the plaintext is never persisted and cannot be recovered. If you lose it, rotate the token in the dashboard and update your connector.

A token looks like:

ftc_live_8f3c2a7b8e1d4056a1b2c3d4e5f60718

The ftc_live_ prefix marks it as a connector token; the rest is the secret. Treat it like a password — anyone holding it can drive the character.

Send the token

Send your token on every request in the X-Connector-Token header:

bash

curl https://api-talk.fluidvip.com/api/v1/characters/chat \
  -H "X-Connector-Token: ftc_live_8f3c2a7b8e1d4056a1b2c3d4e5f60718" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram","handle":"mark","message":"hey"}'

The token authenticates the character; the body's platform field selects the workflow. There is no other credential to send.

The SDKs handle this for you

You configure the token once when you construct the client; every call thereafter is authenticated automatically.

python

# pip install fluidtalk
from fluidtalk import FluidTalk

ft = FluidTalk(token="ftc_live_8f3c2a7b8e1d4056a1b2c3d4e5f60718")

reply = ft.chat(platform="instagram", handle="mark", message="hey")  # token travels on every request

typescript

// npm install fluidtalk
import { FluidTalk } from "fluidtalk";

const ft = new FluidTalk({ token: "ftc_live_8f3c2a7b8e1d4056a1b2c3d4e5f60718" });

const reply = await ft.chat({ platform: "instagram", handle: "mark", message: "hey" }); // token travels on every request

Prefer reading the token from an environment variable or secret manager rather than hard-coding it. The constructor also accepts base_url (defaults to the production base above) and timeout. See Security for handling and rotation guidance.

The token is the character

There is no account-level API key in FluidTalk, and no character_id field anywhere in the API. The connector token is the character's identity:

One token = one character. Authenticating with a token addresses exactly that persona. To drive a different character, use that character's token.
No character_id. You never pass an id — the token already names the character.
Platform lives in the body. Every request takes a platform field (e.g. "instagram"), which selects the workflow bound to that platform in the dashboard. A lead is then identified by (platform, handle) — see Concepts.

This keeps the surface small: hold a token, name a platform and a handle, and the API generates the character's messages and tracks the relationship as one coherent, cross-surface-aware persona. (It never posts anything itself — how you connect to the platform is your concern.)

One token, every platform

A character can run on several platforms at once — Instagram, Twitter/X, Reddit, Fanvue, TikTok, anything. The same token works for all of them. You do not mint a token per platform; you select the platform per request:

bash

# Same token, different bound workflows — chosen by the platform field.
curl https://api-talk.fluidvip.com/api/v1/characters/chat \
  -H "X-Connector-Token: ftc_live_8f3c2a7b8e1d4056a1b2c3d4e5f60718" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram","handle":"mark","message":"hey"}'

curl https://api-talk.fluidvip.com/api/v1/characters/chat \
  -H "X-Connector-Token: ftc_live_8f3c2a7b8e1d4056a1b2c3d4e5f60718" \
  -H "Content-Type: application/json" \
  -d '{"platform":"reddit","handle":"mark","message":"hey"}'

If a character has no workflow bound for the platform you pass, that platform's calls behave as configured in the dashboard (for example, comment endpoints return ignored: "comments not configured"). Bind a workflow per platform before driving it.

Multiple accounts on one platform

A single character can run several accounts on the same platform — for example two Instagram accounts that should never both reply to the same lead. The token is unchanged; you disambiguate the receiving account with own_username:

Pass own_username (the bot account that received the inbound) on POST /chat and POST /triggers.
Pass ?own_username= on GET /followups.

With dedup enabled on the character, the first account a lead messages claims that lead, and inbound from a different account is ignored (the call returns ignored: true, so you send nothing). With no own_username, behavior is the normal single-account path.

TIP

own_username is optional and only relevant when one character fronts more than one account on a platform. See Multi-account dedup for the full "mother-slave" model.

Rotating or losing a token

Because the token is the character, treat rotation as a credential rollover:

In the dashboard, open the character's API tab and Rotate the connector token. The old token stops working. (Delete on the same tab revokes access entirely, with no replacement issued.)
Copy the new secret immediately (again, shown once).
Update your connector's configuration and redeploy.

Rotating the token does not change the character, its bound workflows, its leads, or any in-flight conversations — only the secret used to authenticate changes.

Running a character is metered

Authentication and billing are separate. A token can be perfectly valid yet a turn can still be refused if the character owner's wallet can't cover the upstream model spend — in that case the API returns 402 payment_required before any model call, so you are never charged for a refused turn. Top up the wallet in the dashboard. See Billing for the metering model and the billing object on responses.

What an invalid token returns

Condition	Status	`error.code`
No token sent	`401`	`invalid_token`
Malformed / unknown / rotated-away token	`401`	`invalid_token`
Valid token, action not permitted	`403`	`forbidden`
Valid token, wallet can't cover the turn	`402`	`payment_required`

Every error uses the standard envelope:

json

{
  "error": {
    "code": "invalid_token",
    "message": "Invalid connector token",
    "type": "client_error",
    "request_id": "req_8f3c2a7b"
  }
}

A 401 means re-check the credential: the token is missing, mistyped, or was rotated away in the dashboard. A 403 means the credential is recognized but not permitted for that action. A 402 means the token is fine, but the wallet needs a top-up. The SDKs map 401 to AuthError, 402 to PaymentRequiredError, and 403 to PermissionError. The complete catalog is on the Errors page.

Rate limits

Limits are enforced per connector token. Exceeding a limit returns 429 with error.code rate_limited and a Retry-After header. See Rate limits for the full guidance and back-off strategy.

Next steps

Quickstart — make your first authenticated call end to end.
Concepts — characters, platforms, handles, sessions, and people.
Multi-account dedup — running several accounts per platform.
API reference — every endpoint and its request shape.
Billing — metered usage, the wallet, and 402 payment_required.
Security — storing and rotating your connector token.

Authentication ​

Get a token ​

Send the token ​

The SDKs handle this for you ​

The token is the character ​

One token, every platform ​

Multiple accounts on one platform ​

Rotating or losing a token ​

Running a character is metered ​

What an invalid token returns ​

Rate limits ​

Next steps ​