# Bluesky

Connect a Bluesky account using local loopback or public HTTPS OAuth.

URL: /docs/providers/bluesky

Connect your Bluesky account through OAuth; you do not need to give Postdot your
account password.

You need a Bluesky channel in your project and permission to edit it. An installation
administrator must first configure and activate an OAuth application. If that is
already done, go to [authorize your account](#authorize-your-account).

## Configure the installation [#configure-the-installation]

Choose the mode that matches where Postdot runs. This setup belongs to the
installation administrator; editors can then use it to connect their channels.

### Browser and server on the same machine [#browser-and-server-on-the-same-machine]

Configure a Bluesky OAuth application in **Local loopback** mode. Leave **Client metadata URL** empty. Use
`127.0.0.1` consistently for Postdot's origin and the address opened in the browser.
The default local Docker address is `http://127.0.0.1:3000`.

This mode needs no public metadata endpoint, tunnel or provider developer app.
A 404 at `/oauth/bluesky/client-metadata.json` is expected in loopback mode.
Do not switch between `localhost` and `127.0.0.1` during authorization: the Postdot
session is tied to its host. A remote server opened from your laptop is not this
local-loopback arrangement.

### Remote access over HTTPS [#remote-access-over-https]

Configure the instance's canonical HTTPS origin and select **Public HTTPS**.
A typical deployment uses:

```text
Client metadata URL: https://postbot.example/oauth/bluesky/client-metadata.json
Callback: https://postbot.example/api/oauth/bluesky/callback
```

Replace the example origin. The metadata URL must be publicly fetchable and describe
the callback of the same deployment. Postdot serves this document; it does not need
a separate metadata server or a Bluesky client secret. Save and activate the OAuth
application before connecting a channel.

## Authorize your account [#authorize-your-account]

1. Open the Bluesky channel in **Channels** and start its connection.
2. Enter your **Bluesky handle**, with or without `@`. Custom-domain handles work.
3. Select the configured OAuth application if Studio offers a choice.
4. Continue to Bluesky, check the account and requested access, then authorize.
5. Return to Studio and check the account attached to the channel.

## If the connection fails [#if-the-connection-fails]

- Metadata cannot be fetched: check the public URL and HTTPS reachability, or use
  loopback only when the browser and server are actually local.
- Callback loses your Postdot session: check the host and origin used throughout
  the flow, including reverse-proxy configuration.
- Authorization was declined, expired or already used: start again from the channel.

Once connected, follow [your first publication](/docs/first-publication/) to save a
text draft. Studio checks image and video constraints when you add media.

See the [Bluesky OAuth documentation](https://bsky.network/docs/oauth-client/) for
the underlying protocol, and [installation](/docs/installation/) for origin setup.