Auth

Auth is the first part of our docs for a reason! You don't need to be authed to read records or even to stream data from the firehose. But if you're building an app that integrates with the Atmosphere, you'll begin with auth.

You might start out by just using Atproto identities as an OAuth source — though you'll find that there's lots more you can do by building on top of the Atproto social graph.

This section is aimed at developers building applications on Atproto. Applications with their own end-user login flow should implement OAuth for authentication. Single-purpose applications such as bots or command line tools may use password authentication instead.

We also support the use of App Passwords. Accounts can create and revoke app passwords separate from their primary password. This way, you do not need to supply your primary password to applications that use password auth.

To implement OAuth in your application, refer to OAuth patterns for common use cases, and the Scopes guide for understanding permission models. If you're building your own protocol implementation or OAuth Client SDK, refer to the OAuth spec.

What is OAuth?

OAuth is an authorization framework that lets developers request access to an account without requiring users to hand over their password. Without OAuth, if someone wanted to authorize a 3rd party app to access their account, their only option would be to type their username and password into that app. This is bad for all sorts of reasons, the first being that a 3rd party app gets to see, and likely save, passwords. And once an app has a username and password, the app would have full access to their account.

OAuth aims to solve these problems with a family of open specifications for managing secure authorization without requiring a person's username and password. If you've ever used a "Sign in with..." button or link on the web, you've used OAuth.

As a developer, you can request limited access to a person's account, meaning if you only need to post a message to someone's public timeline, you don't also need to request access to read their private messages. This is great for your app because you don't have to worry about managing data you don't need, and it's great for the person using your app because they don't need to worry about their DMs being compromised.

How is OAuth Different in AT Protocol?

Atproto specifies a particular "profile" of the OAuth standards, using OAuth 2.1 as the foundation.

There are a few details that might catch you off guard if you're used to using other OAuth systems.

Atproto is distributed: Usually, when an app has a "sign in with..." button, it provides a choice of which authorities it allows to authenticate users (usually one of a few big corporations). With ATProto OAuth, the app has no prior relationship with the authentication provider: a user's PDS. This is also the reason why Atproto OAuth is not compatible with OIDC, which requires a pre-established relationship.
Migration: Atproto users can migrate their accounts between servers (PDSes) over time. To facilitate this Atproto has a flexible Identity layer, which allows usernames (handles) to be resolved to a static user ID (DID), which in turn can be resolved to locate the user's PDS. When a user logs in to an app, the OAuth client dynamically resolves these relationships.
Client IDs: In other OAuth ecosystems, it is often necessary for client apps to pre-register themselves with the resource server. This is not viable in a decentralized system (with many clients and many resource servers), so Atproto addresses this using Client ID Metadata Documents.

Getting Started

About authorization

What is OAuth?

How is OAuth Different in AT Protocol?

Further Reading and Resources