Bluesky Getting Started: Account, Keys, and First Request (2026)

Getting started overview

Getting started with Bluesky development involves interacting with the underlying Authenticated Transfer Protocol (AT Protocol). This protocol defines the specifications for decentralized social applications, including identity, data repositories, and federation. Developers typically begin by establishing a Bluesky Social account, which serves as their primary identity on the network and provides the necessary credentials for API access. The AT Protocol is designed to be open and extensible, allowing for custom client and service implementations.

The core steps to initiate development include:

1. Account Creation: Register for a Bluesky Social account. This establishes your Decentralized Identifier (DID) and provides access to the network.
2. Credential Generation: Generate an "app password" from your account settings. This password, combined with your username, is used for authenticating API calls.
3. Environment Setup: Choose a development environment and potentially install the official TypeScript/JavaScript SDK to streamline interactions with the AT Protocol.
4. First Request: Make an authenticated API call, such as fetching your own profile or posting content, to confirm your setup.

The AT Protocol documentation provides comprehensive details on the protocol's architecture and API endpoints, which are organized into Lexicon schemas. These schemas define the data structures and methods for various operations within the Bluesky ecosystem.

Quick Reference Guide

Create an account and get keys

To interact with the Bluesky network programmatically, you first need a user account and an associated app password. Bluesky uses a decentralized identity system where each user has a Decentralized Identifier (DID), which is a self-sovereign identifier that can be resolved to a document containing public keys and service endpoints. Your Bluesky Social account is linked to such a DID.

Account Creation

Begin by creating an account on the Bluesky Social platform. This process typically involves selecting a handle (e.g., @yourname.bsky.social) and providing an email address for verification. Once your account is active, you will have a profile on the Bluesky network.

Generating App Passwords

Bluesky uses app passwords for API authentication instead of your primary account password. This is a security best practice, as it allows you to revoke access for specific applications without compromising your main account. To generate an app password:

1. Log in to your Bluesky Social account.
2. Navigate to your Settings.
3. Look for the App Passwords section (the exact path may vary slightly with app updates).
4. Click on "Add New App Password" or a similar option.
5. Provide a descriptive name for the app password (e.g., "My API Client").
6. A unique app password will be generated. Copy this password immediately, as it is usually displayed only once.

This app password, along with your Bluesky handle (username), will serve as your credentials for making authenticated requests to the AT Protocol. The AT Protocol authentication documentation provides further details on how these credentials are used.

Your first request

After creating an account and obtaining an app password, the next step is to make an authenticated API request. This guide will demonstrate using the official TypeScript/JavaScript SDK, which simplifies interaction with the AT Protocol. The AT Protocol is built on HTTP and JSON, so direct HTTP requests are also possible, but the SDK abstracts away many complexities.

Prerequisites

• Node.js installed
• A Bluesky account and an app password

Install the SDK

Open your terminal or command prompt and install the official AT Protocol SDK:

npm install @atproto/api

Make an Authenticated Call

Create a new JavaScript or TypeScript file (e.g., firstRequest.js) and add the following code. Replace YOUR_BLUESKY_HANDLE and YOUR_APP_PASSWORD with your actual credentials.

import { BskyAgent } from '@atproto/api';

const agent = new BskyAgent({
  service: 'https://bsky.social',
});

async function loginAndFetchProfile() {
  try {
    // 1. Authenticate with your handle and app password
    const response = await agent.login({
      identifier: 'YOUR_BLUESKY_HANDLE', // e.g., 'yourname.bsky.social'
      password: 'YOUR_APP_PASSWORD',   // The app password you generated
    });

    console.log('Login successful:', response.data.did);

    // 2. Fetch your own profile using your DID
    const profile = await agent.getProfile({
      actor: response.data.did, // Use your authenticated DID
    });

    console.log('Fetched profile:', profile.data);

    // Example: Post a simple text skeet (tweet)
    const postResponse = await agent.post({
      text: 'Hello, Bluesky from apispine! This is my first programmatic post. #apispine #bluesky',
    });
    console.log('Posted new skeet:', postResponse.uri);

  } catch (error) {
    console.error('Error during Bluesky API call:', error.message);
    if (error.response) {
      console.error('API Error Response:', error.response.data);
    }
  }
}

loginAndFetchProfile();

Run the script from your terminal:

node firstRequest.js

If successful, you will see output indicating a successful login, your fetched profile data, and the URI of your new post. This confirms that your setup is correct and you can now interact with the Bluesky network programmatically.

The BskyAgent instance connects to the main Bluesky PDS (Personal Data Server) at https://bsky.social. The AT Protocol is designed to be federated, meaning users could potentially host their data on different PDS instances, but for most initial development, the primary Bluesky PDS is the default target.

Common next steps

After successfully making your first request, several common next steps can deepen your integration and development on the Bluesky platform:

1. Explore the AT Protocol API Reference: Dive deeper into the AT Protocol API reference. Understand the various Lexicon schemas for different operations, such as managing repositories (com.atproto.repo), interacting with feeds (app.bsky.feed), and handling profiles (app.bsky.actor). This will enable you to build more complex applications.

2. Understand DIDs and Data Repositories: The AT Protocol's architecture centers around Decentralized Identifiers (DIDs) and personal data repositories. Each user's data (posts, likes, follows) is stored in their own repository, which is cryptographically signed. Understanding how DIDs resolve and how repositories function is crucial for building robust decentralized applications. The AT Protocol identity documentation provides foundational knowledge.

3. Implement Webhooks and Event Streams: For real-time applications, investigate how to subscribe to event streams from the AT Protocol. This allows your application to react to new posts, likes, and other activities across the network without constant polling. The AT Protocol supports a firehose-like stream of events for public-facing applications.

4. Build Custom Feeds: One of Bluesky's key features is the ability to create and subscribe to custom algorithmic feeds. Learn how to define your own feed algorithms using the AT Protocol's feed generator specification. This enables you to curate content based on specific criteria or user preferences.

5. Contribute to Open Source: Bluesky and the AT Protocol are open-source projects. Consider exploring the Bluesky Social GitHub repositories to contribute, report issues, or study existing implementations. This can provide valuable insights into best practices and the underlying architecture.

6. Explore Other SDKs/Libraries: While the official TypeScript SDK is comprehensive, the open-source nature of the AT Protocol may lead to community-contributed SDKs in other languages. Investigate if there are libraries suitable for your preferred development language if it's not TypeScript/JavaScript.

Troubleshooting the first call

When making your first API call to Bluesky, you might encounter issues. Here are common problems and their solutions:

• Invalid Credentials (InvalidToken or AuthenticationFailed):

  • Issue: This is the most frequent error, indicating that your handle or app password is incorrect.
  • Solution: Double-check your Bluesky handle (e.g., yourname.bsky.social) and ensure the app password is exactly as generated, without any extra spaces or typos. Remember that app passwords are case-sensitive. Generate a new app password if you are unsure or suspect a copy-paste error.

• Network Issues (FetchError or NetworkError):

  • Issue: Your application cannot reach the Bluesky service.
  • Solution: Verify your internet connection. Ensure there are no firewalls or proxy settings blocking outgoing HTTP/HTTPS requests from your development environment. Confirm that the service URL (https://bsky.social) is correct and accessible.

• SDK Initialization Errors (BskyAgent related):

  • Issue: Problems with how the BskyAgent is configured.
  • Solution: Ensure you are importing BskyAgent correctly: import { BskyAgent } from '@atproto/api';. Verify that the service URL is set to https://bsky.social.

• Rate Limiting (RateLimitExceeded):

  • Issue: You've made too many requests in a short period.
  • Solution: The AT Protocol, like many APIs, implements rate limiting to prevent abuse. Wait for a short period (e.g., a few minutes) before retrying your request. For production applications, implement exponential backoff and retry logic.

• Lexicon Schema Mismatch:

  • Issue: While less common for initial setup, if you are directly interacting with specific endpoints, you might send data that doesn't conform to the expected Lexicon schema.
  • Solution: Refer to the AT Protocol API documentation for the specific endpoint you are calling to ensure your request body matches the required structure. The SDK generally handles this correctly for common operations.

• Outdated SDK Version:

  • Issue: The AT Protocol is under active development, and older SDK versions might not support the latest features or API changes.
  • Solution: Update your @atproto/api package to the latest version: npm update @atproto/api.

When troubleshooting, always check the error message provided by the API or the SDK. These messages often contain specific clues about what went wrong. Logging the full error object can also reveal more details, especially the error.response.data property for HTTP errors returned by the Bluesky service.