Skip to content

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).

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.

csk_<env>_<keyId><secret>
csk_live_a1b2c3d4e5f6abcdefghijklmnopqrstuvwxyz123456
  • csk_ is the fixed prefix of every Pinlyx API key.
  • <env> is live or test, the environment you chose.
  • <keyId> is 12 characters and identifies the key. The key list shows a prefix made of csk_<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.

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:

Terminal window
curl https://api.pinlyx.com/v1/me \
-H "Authorization: Bearer csk_live_..."

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" }
]
}
}

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.

ScopeWhat it allows
contacts:readRead contacts, their tags, custom fields, lead score, activity timeline, conversations and connected accounts
contacts:writeCreate, update and archive contacts; change tags, stage, lead score, assignee and notes
pipelines:readRead pipeline boards and their stage columns
telegram:sendQueue outbound Telegram messages
telegram:readRead the status of a queued Telegram message
twitter:sendSend X direct messages from connected accounts
social:readRead social inbox conversations across every connected network
social:writeReply in the social inbox and mark conversations read
posts:readRead scheduled and published social posts
posts:writeSchedule, edit and cancel social posts
sequences:readList sequences and see their progress
sequences:writePause and resume sequences
deals:readList and read deals
deals:writeCreate deals and move them between stages
tasks:readList and read tasks
tasks:writeCreate tasks and change their status
email:readRead connected mailboxes, threads and messages
email:writeSet the status and assignee of email threads, connect and re-test a mailbox
finance:readRead the finance summary, transactions, invoices and revenue sources
analytics:readRead dashboard figures and messaging statistics
agents:readList and inspect AI agents
agents:runGenerate a test reply from an AI agent. Nothing is sent to a customer.
jobs:readRead the outbound sending queue
webhooks:readList webhook endpoints and their deliveries
webhooks:writeCreate, edit, test, rotate and delete webhook endpoints
ads:readRead connected Google Ads, Meta Ads and TikTok Ads accounts and their performance
ads:writePause campaigns and change budgets, bids and targeting
finance:write sensitiveCreate transactions and mark invoices paid
email:send sensitiveSend an email reply inside an existing thread
keys:manage sensitiveCreate, list and revoke API keys, never with more scopes than the calling key holds
ads:publish sensitivePublish 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.

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 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.

StatusMeaning
401 UnauthorizedThe token is missing, malformed, revoked, expired, or sent over plain HTTP. The response has no body.
403 ForbiddenThe token is valid but lacks the scope the endpoint needs (insufficient_scope), or your workspace role does not allow writes.