audio streaming app
plyr.fm
1---
2title: auth
3sidebarTitle: auth
4---
5
6# `backend.api.auth`
7
8
9authentication api endpoints.
10
11## Functions
12
13### `get_pds_options` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L108)
14
15```python
16get_pds_options() -> PdsOptionsResponse
17```
18
19
20get available PDS options for account creation.
21
22returns the list of recommended PDS hosts where users can create
23new ATProto accounts. this is used by the frontend login page to
24show the "create account" option.
25
26
27### `start_login` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L132)
28
29```python
30start_login(request: Request, handle: str | None = None, pds_url: str | None = None) -> RedirectResponse
31```
32
33
34start OAuth flow for login or account creation.
35
36for login: provide `handle` to authenticate with an existing account.
37for account creation: provide `pds_url` to create a new account on that PDS.
38
39exactly one of `handle` or `pds_url` must be provided.
40
41
42### `oauth_callback` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L172)
43
44```python
45oauth_callback(code: Annotated[str, Query()], state: Annotated[str, Query()], iss: Annotated[str, Query()]) -> RedirectResponse
46```
47
48
49handle OAuth callback and create session.
50
51returns exchange token in URL which frontend will exchange for session_id.
52exchange token is short-lived (60s) and one-time use for security.
53
54handles four flow types based on pending state:
551. developer token flow - creates dev token session, redirects with dev_token=true
562. scope upgrade flow - replaces old session with new one, redirects to settings
573. add account flow - creates session in existing group, redirects to portal
584. regular login flow - creates session, redirects to portal or profile setup
59
60
61### `exchange_token` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L327)
62
63```python
64exchange_token(request: Request, exchange_request: ExchangeTokenRequest, response: Response) -> ExchangeTokenResponse
65```
66
67
68exchange one-time token for session_id.
69
70frontend calls this immediately after OAuth callback to securely
71exchange the short-lived token for the actual session_id.
72
73for browser requests: sets HttpOnly cookie and still returns session_id in response
74for SDK/CLI clients: only returns session_id in response (no cookie)
75for dev token exchanges: returns session_id but does NOT set cookie
76
77
78### `logout` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L381)
79
80```python
81logout(session: Session = Depends(require_auth), switch_to: Annotated[str | None, Query(description='DID to switch to after logout')] = None, db = Depends(get_db)) -> JSONResponse
82```
83
84
85logout current user.
86
87if switch_to is provided and valid, deletes current session and switches
88to the specified account. otherwise, fully logs out.
89
90
91### `get_current_user` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L447)
92
93```python
94get_current_user(session: Session = Depends(require_auth), db = Depends(get_db)) -> CurrentUserResponse
95```
96
97
98get current authenticated user with linked accounts.
99
100
101### `get_developer_tokens` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L482)
102
103```python
104get_developer_tokens(session: Session = Depends(require_auth)) -> DeveloperTokenListResponse
105```
106
107
108list all developer tokens for the current user.
109
110
111### `delete_developer_token` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L502)
112
113```python
114delete_developer_token(token_prefix: str, session: Session = Depends(require_auth)) -> JSONResponse
115```
116
117
118revoke a developer token by its prefix (first 8 chars of session_id).
119
120
121### `start_developer_token_flow` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L542)
122
123```python
124start_developer_token_flow(request: Request, body: DevTokenStartRequest, session: Session = Depends(require_auth)) -> DevTokenStartResponse
125```
126
127
128start OAuth flow to create a developer token with its own credentials.
129
130this initiates a new OAuth authorization flow. the user will be redirected
131to authorize, and on callback a dev token with independent OAuth credentials
132will be created. this ensures dev tokens don't become stale when browser
133sessions refresh their tokens.
134
135returns the authorization URL that the frontend should redirect to.
136
137
138### `start_scope_upgrade_flow` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L603)
139
140```python
141start_scope_upgrade_flow(request: Request, body: ScopeUpgradeStartRequest, session: Session = Depends(require_auth)) -> ScopeUpgradeStartResponse
142```
143
144
145start OAuth flow to upgrade session scopes.
146
147this initiates a new OAuth authorization flow with expanded scopes.
148the user will be redirected to authorize, and on callback the old session
149will be replaced with a new session that has the requested scopes.
150
151use this when a user enables a feature that requires additional OAuth scopes
152(e.g., enabling teal.fm scrobbling which needs fm.teal.alpha.* scopes).
153
154returns the authorization URL that the frontend should redirect to.
155
156
157### `start_add_account_flow` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L655)
158
159```python
160start_add_account_flow(request: Request, body: AddAccountStartRequest, session: Session = Depends(require_auth)) -> AddAccountStartResponse
161```
162
163
164start OAuth flow to add another account to the session group.
165
166the user must provide the handle of the account they want to add.
167this initiates a new OAuth authorization flow with prompt=login to force
168fresh authentication. the new account will be linked to the same session
169group as the current account, enabling quick switching between accounts.
170
171returns the authorization URL that the frontend should redirect to.
172
173
174### `switch_account` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L705)
175
176```python
177switch_account(body: SwitchAccountRequest, response: Response, session: Session = Depends(require_auth), db = Depends(get_db)) -> SwitchAccountResponse
178```
179
180
181switch to a different account in the session group.
182
183switches the active account within the session group. the cookie is updated
184to point to the new session, and the old session is marked inactive.
185
186returns the new active account's info.
187
188
189### `logout_all` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L767)
190
191```python
192logout_all(session: Session = Depends(require_auth), db = Depends(get_db)) -> JSONResponse
193```
194
195
196logout all accounts in the session group.
197
198removes all sessions in the group and clears the cookie.
199
200
201## Classes
202
203### `LinkedAccountResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L52)
204
205
206account info for account switcher UI.
207
208
209### `CurrentUserResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L60)
210
211
212response model for current user endpoint.
213
214
215### `DeveloperTokenInfo` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L69)
216
217
218info about a developer token (without the actual token).
219
220
221**Methods:**
222
223#### `truncate_session_id` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L79)
224
225```python
226truncate_session_id(cls, v: str) -> str
227```
228
229truncate to 8-char prefix for safe display.
230
231
232### `DeveloperTokenListResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L84)
233
234
235response model for listing developer tokens.
236
237
238### `PdsOption` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L90)
239
240
241a PDS option for account creation.
242
243
244### `PdsOptionsResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L100)
245
246
247response model for PDS options endpoint.
248
249
250### `ExchangeTokenRequest` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L313)
251
252
253request model for exchanging token for session_id.
254
255
256### `ExchangeTokenResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L319)
257
258
259response model for exchange token endpoint.
260
261
262### `DevTokenStartRequest` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L527)
263
264
265request model for starting developer token OAuth flow.
266
267
268### `DevTokenStartResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L534)
269
270
271response model with OAuth authorization URL.
272
273
274### `ScopeUpgradeStartRequest` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L588)
275
276
277request model for starting scope upgrade OAuth flow.
278
279
280### `ScopeUpgradeStartResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L595)
281
282
283response model with OAuth authorization URL.
284
285
286### `AddAccountStartRequest` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L641)
287
288
289request model for starting add-account flow.
290
291
292### `AddAccountStartResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L647)
293
294
295response model with OAuth authorization URL for adding account.
296
297
298### `SwitchAccountRequest` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L690)
299
300
301request model for switching to a different account.
302
303
304### `SwitchAccountResponse` [source](https://github.com/zzstoatzz/plyr.fm/blob/main/backend/src/backend/api/auth.py#L696)
305
306
307response model after switching accounts.
308