Latch - an atproto OAuth client library

As part of building a service for automatically publishing blog posts from RSS feeds into atproto’s standard.site lexicon, I implemented atproto OAuth for logging in and getting access tokens to publish for the user. This means that any user with an atproto account, whether they created it on Bluesky, Eurosky, or Blacksky, or any of the other Personal Data Servers available, can log in to your service. Atproto OAuth does not require pre-registering clients with a service, one implementation works across the entire ecosystem.

The OAuth implementation is based on the 2.1 specification with some still in-draft extensions, and comes with some quirks compared to what you’d expect from older generations of OAuth. For example, access tokens can’t be used as is, they need to come with a DPoP (demonstrating proof of possession) header signed for the specific request you’re making, limiting what the access token can be used for if stolen. Additionally it includes PAR (push authorization request) and some other fun stuff.

The goal of Latch is to provide an idiomatic Elixir implementation that deals with all of this for you, while maintaining flexibility and enabling things like setting up multiple OAuth clients in the same project, and starting them ad-hoc on command.

• Github GitHub - joladev/latch: An Elixir atproto OAuth and XRPC client · GitHub
• Tangled jola.dev/latch at main · Tangled
• hexpm: latch | Hex
• docs: Latch — latch v0.5.0

Quickstart

Add Latch to your project.

def deps do
  [
    {:latch, "~> 0.5.0"}
  ]
end

Create a Latch Store module for storing in-progress requests and access tokens.

defmodule MyApp.LatchStore do
  use Latch.Store.ETS
end

Add it and your Latch instance to your supervision tree.

children = [
  {MyApp.LatchStore, []},
  {Latch,
    name: MyApp.Latch,
    mode: :confidential,
    store: MyApp.LatchStore,
    client_id_path: "/oauth-client-metadata.json",
    redirect_uri_path: "/auth/callback",
    base_url_fn: &MyAppWeb.Endpoint.url/1,
    scope: "atproto",
    signing_key: System.fetch_env!("ATPROTO_CLIENT_PRIVATE_JWK")}
]

Set up a route to serve the CIMD (client ID metadata document) at /oauth-client-metadata.json.

def client_metadata(conn, _params) do
  json(conn, Latch.client_metadata(MyApp.Latch))
end

Now the rest of it is fairly recognizable if you’ve done OAuth before. Call authorize when a user has passed their handle to log in, redirect them to the URL you get back, and then provide a callback URL to finish the flow.

# call when the user clicks log in
{:ok, url} = Latch.authorize(MyApp.Latch, "alice.bsky.social")
# send to the user to the url

# expose a callback endpoint and call callback
{:ok, %{did: did, handle: handle}} = Latch.callback(MyApp.Latch, conn.params)
# and you're done, the access token lives in Latch

Now you can hit private endpoints or write to the user’s atproto PDS, according to the scopes you requested. Here’s are some example requests. Note that access tokens are managed and refreshed automatically by the library.

{:ok,
  %{
    "uri" => "at://did:plc:abc123/app.bsky.feed.post/3k2...",
    "cid" => "bafyreid...",
    "value" => %{
      "$type" => "app.bsky.feed.post",
      "text" => "Hello atproto",
      "createdAt" => "2026-07-31T12:00:00.000Z"
    }
  }} =
  Latch.query(MyApp.Latch, did, "com.atproto.repo.getRecord",
    params: [
      repo: did,
      collection: "app.bsky.feed.post",
      rkey: "3k2..."
    ]
  )

{:ok,
  %{
    "uri" => "at://did:plc:abc123/app.bsky.feed.post/3k5...",
    "cid" => "bafyreig..."
  }} =
  Latch.procedure(MyApp.Latch, did, "com.atproto.repo.createRecord", %{
    repo: did,
    collection: "app.bsky.feed.post",
    record: %{text: "Hello atproto", createdAt: DateTime.utc_now()}
  })

I’ve previously written a bit about atproto and Latch on https://blog.annot.at. I’m also planning to write more on my personal blog!