---
title: "Connect a credential-based account directly"
method: POST
path: "/api/v1/connect/{platform}/credentials"
tags: ["Connections"]
---

# Connect a credential-based account directly

`POST /api/v1/connect/{platform}/credentials`

## Request

- Base URL: `https://www.poster.ly`
- URL: `https://www.poster.ly/api/v1/connect/{platform}/credentials`
- Auth: HTTP bearer

Headless connection for credential-based platforms: telegram, bluesky, discord, wordpress, devto, hashnode, and lemmy. Call `GET /api/v1/connect/{platform}` first: `credential_fields` lists exactly which keys to send, and `supports_direct_credentials` confirms the platform accepts this flow. OAuth platforms and mastodon are rejected with `credentials_not_supported`; create a browser connect session for those instead. Upsert semantics: reconnecting the same account updates it in place and returns 200 either way. Prefer scoped secrets (app passwords, bot tokens, webhook URLs, API tokens) over primary passwords. Credential values are never echoed back in errors or logs. Rate limit: 20 credential connect attempts per hour per user.

## Path parameters

- `platform` string, required

## Request body

- ConnectCredentialsRequest
  - `credentials` object, required: Credential fields for the platform, exactly the keys listed in the connect option credential_fields. Unknown keys are rejected; required keys must be non-empty strings. Values are used to authenticate with the provider and are never echoed back.
  - `workspace_id` string, uuid: Optional workspace to connect the account into. You must be a member. Workspace-scoped API keys ignore this and use their bound workspace.
  - `connect_session_id` string, uuid: Optional connect session created via POST /api/v1/connect/{platform}/sessions; it is marked connected or failed based on the outcome.

## Response `200`

Account connected (or reconnected) successfully

- ConnectCredentialsResponse
  - `connected` boolean, required
  - `account` object, required
    - `id` integer, required
    - `platform` string, required
    - `username` string, required
  - `workspace_id` string, uuid, required

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `403`: Request is authenticated but not allowed
- `404`: Resource not found
- `429`: Too many requests

---

[API](https://skmtc.dev/poster/apis/posterly-api.md) · [All operations](https://skmtc.dev/poster/apis/posterly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/poster/apis/posterly-api/revisions/60be02a61f95?raw)