n8n-nodes-tokportal

This is an n8n community node package for TokPortal.

TokPortal is the managed social infrastructure API: real TikTok and Instagram accounts created, warmed and operated by human account managers in 16+ countries — exposed as a REST API and an MCP server. No OAuth per account, no 25-posts/day cap, no app review.

The package ships two nodes:

• TokPortal — an action node covering bundles (missions), videos, delivered accounts, media, credits, webhook endpoints, analytics, Advanced Niche Warming and workspace helpers (52 operations, declarative/routing style, usable as an AI Agent tool).
• TokPortal Trigger — a webhook trigger that registers a signed TokPortal webhook endpoint when the workflow is activated and starts the workflow on the events you pick (account delivered, video posted, account banned, warming completed, subscription changes, ...).

Installation · Credentials · Operations · Trigger · Templates · MCP alternative · Resources · Support

Installation

n8n Cloud and self-hosted (GUI)

1. Open Settings → Community Nodes.
2. Click Install, enter n8n-nodes-tokportal and confirm.
3. The TokPortal and TokPortal Trigger nodes appear in the nodes panel.

Self-hosted (CLI / Docker)

# inside your n8n user folder (~/.n8n by default)
cd ~/.n8n && mkdir -p nodes && cd nodes
npm install n8n-nodes-tokportal
# restart n8n

Or set N8N_COMMUNITY_PACKAGES=n8n-nodes-tokportal for a Docker install. See the n8n community nodes documentation for details.

Requirements: n8n ≥ 1.0 (Node.js ≥ 20.15). No runtime dependencies.

Credentials

Create a TokPortal API credential with your API key:

1. Sign in to app.tokportal.com → Developer → API keys → create a key (starts with sk_; shown once).
2. In n8n: Credentials → New → TokPortal API, paste the key and click Save. n8n tests it against GET /me.

Every request is sent with X-API-Key: sk_... and X-TokPortal-Client: n8n-nodes-tokportal/<version> to https://app.tokportal.com/api/ext. The same credential can be selected in n8n's HTTP Request node (Authentication → Predefined Credential Type → TokPortal API) for endpoints not covered here.

Operations

All operations return the TokPortal data object(s) as n8n items. Mutations that add metadata (for example credits_charged on bundle creation) keep it under _meta. List operations expose Return All (auto-pagination) and Limit.

Notes and gotchas:

• Credits are debited on Bundle → Create, not on publish. Check Credit → Get Costs and Bundle → Get Publish Readiness first if you automate at scale.
• Video → Configure takes a public direct video URL (.mp4) or a TokPortal storage URL. To upload a file from n8n, use Media → Create Video Upload URL, PUT the binary to upload_url with an HTTP Request node, then pass public_url as Video URL (template 06 shows the full flow). Direct multipart upload (POST /upload/video/direct) is not wrapped by this node — call it with the HTTP Request node and the same credential (Body → Form-Data, file + bundle_id).
• Account → Reveal Credentials / Retrieve Verification Code are irreversible first-access events and, on new-policy accounts, end TokPortal Coverage. The API answers HTTP 428 with error.details.policy_version on the first call; run the operation again with Acknowledge Support Forfeit enabled and that exact Policy Version. Template 07 wires this behind a manual approval. Never post revealed secrets to chat tools.
• Comma-separated fields (warming terms, carousel images, tags, collaborators) also accept an array through an expression, e.g. {{ $json.terms }}.
• Advanced Niche Warming is the only warming TokPortal sells, and its opt-in is never inferred: turn on Advanced Niche Warming on Create Bundle / Create Bundles (Bulk) before setting terms or a target count, otherwise the API refuses the call with ADVANCED_WARMING_FLAG_REQUIRED (nothing is charged). Send the terms or the count, not two quantities that disagree, and keep the terms distinct — a duplicate fails the call with ADVANCED_WARMING_TERMS_REJECTED instead of silently reducing what you buy.
• Platform values accepted for new bundles are tiktok and instagram. YouTube channels are delivered through the TokPortal dashboard and then usable through the account and video operations.
• Bundle creation, webhook creation and presigned uploads must not be retried with an Idempotency-Key; the node never sends one.

The node is marked usableAsTool, so it can be attached to n8n's AI Agent node as a tool.

TokPortal Trigger

Add TokPortal Trigger, pick the credential and the events you want:

webhook.test, bundle.created, bundle.published, bundle.cancelled, bundle.archived, account.configured, account.published, account.in_review, account.pending_corrections, account.finalized, account.remade, account.banned, account.ban_appeal.submitted, account.ban_appeal.resolved, account.ban_resolution.decided, account.revealed, video.configured, video.in_review, video.published, video.pending_corrections, video.finalized, warming.session_started, warming.term_verified, warming.session_completed, subscription.renewed, subscription.lapsed, subscription.cancelled, subscription.reactivated, subscription.ended, credits.restored.

How it works:

• Activate → the node calls POST /webhooks with the n8n webhook URL and your events, and stores the endpoint ID and the one-time signing_secret in the workflow's static data (never in the credential).
• Deactivate / delete → the node calls DELETE /webhooks/{id}.
• Delivery → the node verifies the TokPortal-Signature header (t=<unix_ts>,v1=<hex>, HMAC-SHA256 of "<t>.<raw_body>" with the signing secret, 300 s tolerance by default, constant-time comparison) and rejects invalid requests with 401. Signature verification and tolerance are configurable under Options.
• Output → one item per event with the full envelope (id, type, api_version, created_at, data) plus headers.event_id / headers.event_type. Use id (or headers.event_id) as your idempotency key: retries keep the same event ID.

If you subscribe at minimum to account.banned, bundle.cancelled and account.remade, you get the push signals that a managed account was banned, that a bundle will no longer accept publishes, and that an account was rebuilt (same bundle_id, new saved account).

Testing tip: with Listen for test event active, use Webhook Endpoint → Test (or the dashboard "Send test") to send a signed webhook.test delivery.

Workflow templates

Eight importable workflows live in templates/ — see templates/README.md for setup steps and the Creator Hub descriptions:

1. Google Sheet → TokPortal bundles (bulk account creation)
2. Faceless channel factory (Schedule → render → configure → publish)
3. TokPortal ban → Slack alert (trigger)
4. Daily analytics digest → Slack
5. Airtable UGC queue → TokPortal videos
6. Sora/Veo output URL → TokPortal upload + schedule
7. New account delivered → notify + reveal step (manual approval)
8. Credits balance guard → top-up reminder

Import them from Workflows → Import from File (or paste the JSON), then select your credentials.

Alternative: MCP Client node

If you prefer to let an AI agent drive TokPortal, use n8n's MCP Client Tool node against the hosted TokPortal MCP server (same 90+ tools as the API):

• Endpoint: https://app.tokportal.com/api/ext/mcp (Streamable HTTP)
• Authentication: header Authorization: Bearer sk_... (or X-API-Key: sk_...)

Docs: developers.tokportal.com/mcp.

Compatibility

Built and linted with @n8n/node-cli (declarative node, n8nNodesApiVersion: 1). Tested against n8n-workflow 2.x. Node.js ≥ 20.15.

Development

npm install --ignore-scripts
npm run build      # tsc + static assets → dist/
npm run lint       # n8n community node linter
npm test           # loads dist/, checks every resource/operation, signature verification, templates

Resources

• API documentation: https://developers.tokportal.com
• OpenAPI: https://developers.tokportal.com/openapi.json
• Webhooks & signature scheme: https://developers.tokportal.com/webhooks
• GitHub organisation: https://github.com/tokportal (SDKs for Node, Python, Go, CLI, MCP server)
• n8n community nodes documentation: https://docs.n8n.io/integrations/community-nodes/

Support

• Issues and feature requests: https://github.com/tokportal/n8n-nodes-tokportal/issues
• Email: team@tokportal.com

License

MIT