Skip to content

Connect Bluesky API

The Connect Bluesky API connects a Bluesky account by submitting a user-generated Bluesky app password together with a handle or DID. Bluesky has no OAuth redirect for this flow, so the request uses POST to /v1/connect/bluesky/auth with an x-access-key header and a JSON body containing identifier and password.

Why an app password: no OAuth redirect

Bluesky has no OAuth redirect for this connection flow. The user generates an app password at https://bsky.app/settings/app-passwords, then submits it here. Use an app password, not the account password: the password field must contain the generated credential, and submitting the regular account password is explicitly not supported by the documented contract. The identifier field accepts either a Bluesky handle, for example alice.bsky.social, or a DID, for example did:plc:abc123. As recommended practice, confirm which identifier form you will send before calling, and avoid including the app password in logs or error messages.

Authorization: x-access-key header

Send the access key in the x-access-key header on every request to this endpoint. The header name is exactly x-access-key and its value is the token placeholder shown in the request example titled Connect Bluesky account request example. Do not substitute a different authorization header name for this endpoint.

Request body: identifier and password

Send a JSON request body with two required string fields. The identifier field is required and accepts a Bluesky handle or DID. The password field is required and must hold the credential created through the Bluesky app-password settings page; the regular account password must not be used there. Both fields are required, so a request missing either field does not meet the documented contract. See the request body field map table and the request example titled Connect Bluesky account request example for the exact field names and types.

Query parameters field map

The source page lists seven optional query parameters alongside this endpoint. They are preserved in the query parameters field map table with their exact names, types, constraints, and descriptions. Several descriptions reference Instagram, Facebook, OAuth, or account-selection behavior that does not match the Bluesky app-password flow described in the main text, so check applicability for your use case before relying on any of them for this endpoint. In particular, loginMethod is documented as Instagram only with values instagram_login and facebook_login, reconnectAccountId is documented for an Instagram integration to reconnect with pattern ^[a-fA-F0-9]{24}$, and headless defaults to false. Do not assume these parameters change the Bluesky app-password request body, which remains identifier and password.

Response body: documented errors only

Only error responses are documented for this endpoint. A 400 response, a 401 response, and a 502 response each return a JSON body with a single required error string field, as shown in the error responses table. No successful response body, success status code, or success fields are documented on this page, so do not invent success semantics or reuse success fields from other endpoints. The source does not document a cause for any status code, so handle each by its status code and read the error string without assuming a specific cause.

400 error response

A 400 response returns application/json with the documented error body, which contains a single required error string field. The source does not document a specific cause for this status code.

401 error response

A 401 response returns application/json with the documented error body, which contains a single required error string field. The source does not document a specific cause for this status code.

502 error response

A 502 response returns application/json with the documented error body, which contains a single required error string field. The source does not document a specific cause for this status code.

Request body field map
FieldTypeRequiredConstraintsDescription
identifierstringrequirednone documentedBluesky handle (e.g. "alice.bsky.social") or DID (e.g. "did:plc:abc123").
passwordstringrequirednone documentedAn app password generated at https://bsky.app/settings/app-passwords. Do NOT use the account password.

Exact documented request body contract for POST /v1/connect/bluesky/auth

Query parameters field map
ParameterTypeRequiredConstraintsDescription
loginMethodstringoptionalenum: instagram_login, facebook_loginInstagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app.
reconnectAccountIdstringoptionalpattern: ^[a-fA-F0-9]{24}$Instagram integration to reconnect. Account identity must match; existing posts are retained.
redirectUristringoptionalformat: uriFinal URL to redirect to after the connection completes. In headless mode, this URL also receives selection status query parameters when customer-owned account selection is required.
cancelRedirectUristringoptionalformat: uriURL to redirect to when the user cancels or denies the OAuth prompt. Falls back to redirectUri when omitted.
headlessbooleanoptionaldefault: falseWhen true, platforms that require account selection redirect back to redirectUri with a short-lived selectionToken so you can build your own selection UI. When false, the system hosts the selection UI.
profileIdstringoptionalnone documentedProfile to associate the resulting integration with. Must belong to the same project. Omit to connect without a profile.
appIdstringoptionalnone documentedConnect under your own OAuth app (Bring Your Own Keys). Pass the id of an OAuth app created via /v1/apps for this same platform. Omit to use the system app.

Preserved as listed on source page; applicability to the Bluesky app-password flow is a factual hold because descriptions reference Instagram, Facebook, OAuth and account-selection flows

Error responses failure matrix
StatusContent typeBody fieldTypeRequired
400application/jsonerrorstringrequired
401application/jsonerrorstringrequired
502application/jsonerrorstringrequired

Only documented responses; no successful response is documented on this page and no status cause is documented

Frequently asked questions

Why does this endpoint use an app password instead of OAuth?

Bluesky has no OAuth redirect for this flow. The user generates an app password at https://bsky.app/settings/app-passwords and submits it with their handle or DID. Do not use the account password.

What values can identifier take?

The identifier field accepts a Bluesky handle such as alice.bsky.social or a DID such as did:plc:abc123. The password field accepts only the generated app password, not the account password.

What error body is documented for this endpoint?

The documented error responses for 400, 401, and 502 each use a JSON body with a single error string field. No successful response body is documented on this page, so do not assume success fields from other endpoints.

Connect Bluesky account request example
curl -X POST "{{API_BASE_URL}}/v1/connect/bluesky/auth" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "identifier": "string",
    "password": "string"
  }'
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
loginMethod#1loginMethodstring__0NoInstagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app.
loginMethod#1loginMethod[variant1]string__0_extends:__1Instagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app.kind: schemaValueIn; value: "instagram_login"
loginMethod#1loginMethod[variant2]string__0_extends:__2Instagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app.kind: schemaValueIn; value: "facebook_login"
reconnectAccountId#2reconnectAccountIdstring__0NoInstagram integration to reconnect. Account identity must match; existing posts are retained.kind: schemaMatch; value: ^[a-fA-F0-9]{24}$
redirectUri#3redirectUristring__0NoFinal URL to redirect to after the connection completes. In headless mode, this URL also receives selection status query parameters when customer-owned account selection is required.kind: schemaFormat; value: uri
cancelRedirectUri#4cancelRedirectUristring__0NoURL to redirect to when the user cancels or denies the OAuth prompt. Falls back to redirectUri when omitted.kind: schemaFormat; value: uri
headless#5headlessboolean__0NoWhen true, platforms that require account selection redirect back to redirectUri with a short-lived selectionToken so you can build your own selection UI. When false, the service hosts the selection UI.kind: schemaDefault; value: false
profileId#6profileIdstring__0NoProfile to associate the resulting integration with. Must belong to the same project. Omit to connect without a profile.
appId#7appIdstring__0NoConnect under your own OAuth app (Bring Your Own Keys). Pass the id of an OAuth app created via /v1/apps for this same platform. Omit to use the service's system app.
body#8bodyobject__0Yes
body#8body.identifierstring__1YesBluesky handle (e.g. "alice.bsky.social") or DID (e.g. "did:plc:abc123").
body#8body.passwordstring__2YesAn app password generated at https://bsky.app/settings/app-passwords . Do NOT use the account password.
response#9responseobject__0
response#9response.errorstring__1Yes