Authentication
Every request to the Pinlyx API is authenticated with an API key sent as a bearer token. A key belongs to the account that created it, and carries a fixed set of scopes that decide which endpoints and MCP tools it may call. The same key works for the REST API (/v1) and the MCP server (/mcp).
Create a key
Section titled “Create a key”Open Settings › Developers in the Pinlyx app, stay on the API keys tab and click Create key. Give it a Name, pick the Environment (Live or Test) and tick the Scopes it needs. The full token is shown once, right after you create it; Pinlyx keeps only a hash of the secret. API keys are part of the Business plan.
Key format
Section titled “Key format”csk_<env>_<keyId><secret>csk_live_a1b2c3d4e5f6abcdefghijklmnopqrstuvwxyz123456csk_is the fixed prefix of every Pinlyx API key.<env>isliveortest, the environment you chose.<keyId>is 12 characters and identifies the key. The key list shows a prefix made ofcsk_<env>_and the first 8 of them, so you can tell keys apart.<secret>is the remaining 32 characters.
Both parts use letters and digits only. A token of any other length is rejected as malformed.
Send the key
Section titled “Send the key”Pass the key in the Authorization header with the Bearer scheme. HTTPS is required.
Authorization: Bearer csk_live_...Some MCP gateways do not forward an Authorization header. For those, the same key is also accepted in an X-Api-Key header, with the same scopes and rate limit.
GET /v1/me needs no particular scope, so it is the simplest way to check a key:
curl https://api.pinlyx.com/v1/me \ -H "Authorization: Bearer csk_live_..."const res = await fetch('https://api.pinlyx.com/v1/me', { headers: { Authorization: 'Bearer csk_live_...' },});console.log(await res.json());It returns the account behind the key, the key’s scopes and the workspace it is acting on:
{ "id": 42, "email": "jane@example.com", "name": "Jane Doe", "createdAt": "2026-01-15T09:00:00Z", "apiKey": { "keyId": "a1b2c3d4e5f6", "scopes": ["contacts:read", "telegram:send"] }, "workspace": { "activeId": 7, "role": "Owner", "canWrite": true, "header": "X-Workspace-Id", "available": [ { "id": 7, "name": "Acme", "slug": "acme", "role": "Owner" } ] }}Scopes
Section titled “Scopes”A request to an endpoint whose scope the key does not hold returns 403 with the error insufficient_scope and the scopes that would have been accepted. Give each key only what its job needs.
| Scope | What it allows |
|---|---|
contacts:read | Read contacts, their tags, custom fields, lead score, activity timeline, conversations and connected accounts |
contacts:write | Create, update and archive contacts; change tags, stage, lead score, assignee and notes |
pipelines:read | Read pipeline boards and their stage columns |
telegram:send | Queue outbound Telegram messages |
telegram:read | Read the status of a queued Telegram message |
twitter:send | Send X direct messages from connected accounts |
social:read | Read social inbox conversations across every connected network |
social:write | Reply in the social inbox and mark conversations read |
posts:read | Read scheduled and published social posts |
posts:write | Schedule, edit and cancel social posts |
sequences:read | List sequences and see their progress |
sequences:write | Pause and resume sequences |
deals:read | List and read deals |
deals:write | Create deals and move them between stages |
tasks:read | List and read tasks |
tasks:write | Create tasks and change their status |
email:read | Read connected mailboxes, threads and messages |
email:write | Set the status and assignee of email threads, connect and re-test a mailbox |
finance:read | Read the finance summary, transactions, invoices and revenue sources |
analytics:read | Read dashboard figures and messaging statistics |
agents:read | List and inspect AI agents |
agents:run | Generate a test reply from an AI agent. Nothing is sent to a customer. |
jobs:read | Read the outbound sending queue |
webhooks:read | List webhook endpoints and their deliveries |
webhooks:write | Create, edit, test, rotate and delete webhook endpoints |
ads:read | Read connected Google Ads, Meta Ads and TikTok Ads accounts and their performance |
ads:write | Pause campaigns and change budgets, bids and targeting |
finance:write sensitive | Create transactions and mark invoices paid |
email:send sensitive | Send an email reply inside an existing thread |
keys:manage sensitive | Create, list and revoke API keys, never with more scopes than the calling key holds |
ads:publish sensitive | Publish an ad draft without a person approving it first. Campaigns are still created paused. |
The scopes marked sensitive are never granted by default. Tick them only for a key that needs them.
Workspaces
Section titled “Workspaces”A key acts for the account that created it. When that account belongs to a shared workspace, the key reads and writes the workspace’s contacts, deals and tasks, not just its own. To act inside a specific workspace, send its id in the X-Workspace-Id header. Membership is checked on every request, so the header can never reach a workspace you are not a member of. GET /v1/me lists the workspaces the key can switch to under workspace.available.
A member with the Viewer role can read through the API, but writes to contacts, deals, tasks, finance and social posts return 403.
Live and test keys
Section titled “Live and test keys”live and test are labels you choose when you create a key, so you can keep development keys apart from production ones. Both act on the same workspace data; there is no separate sandbox. A token is only accepted with the environment it was created with.
Authentication errors
Section titled “Authentication errors”| Status | Meaning |
|---|---|
401 Unauthorized | The token is missing, malformed, revoked, expired, or sent over plain HTTP. The response has no body. |
403 Forbidden | The token is valid but lacks the scope the endpoint needs (insufficient_scope), or your workspace role does not allow writes. |