add docs/

.github/pull_request_template.md

@@ -8,6 +8,7 @@ How to test:
 
 - [ ] l10n dependencies have been merged, if any.
 - [ ] I've added a unit test to test for potential regressions of this bug (or this is a front-end change, where we don't yet have unit test infrastructure).
+- [ ] I've added or updated relevant docs in the docs/ directory.
 - [ ] All UI revisions follow the [coding standards](https://github.com/mozilla/fx-private-relay/blob/main/docs/coding-standards.md), and use Protocol tokens where applicable (see `/static/scss/libs/protocol/css/includes/tokens/dist/index.scss`).
 - [ ] Commits in this PR are minimal and [have descriptive commit messages](https://chris.beams.io/posts/git-commit/).
 
@@ -29,5 +30,6 @@ Not applicable.
 
 - [ ] l10n dependencies have been merged, if any.
 - [ ] All acceptance criteria are met.
+- [ ] I've added or updated relevant docs in the docs/ directory.
 - [ ] All UI revisions follow the [coding standards](https://github.com/mozilla/fx-private-relay/blob/main/docs/coding-standards.md), and use Protocol tokens where applicable (see `/static/scss/libs/protocol/css/includes/tokens/dist/index.scss`).
 - [ ] Commits in this PR are minimal and [have descriptive commit messages](https://chris.beams.io/posts/git-commit/).

docs/api_auth.md

@@ -0,0 +1,35 @@
+# Relay API Authentication
+The Relay API is built on [Django REST Framework][drf] and authenticates
+requests with any of 3 methods:
+* [FXA OAuth Token Authentication](fxa-oauth-token-authentication)
+* [`SessionAuthentication`][SessionAuthentication]
+* [`TokenAuthentication`][TokenAuthentication]
+
+## FXA OAuth Token Authentication
+The Relay add-on uses the [`identity.launchWebAuthFlow` API][mdn-webauthflow]
+to perform an OAuth2 flow with [the FXA OAuth service][fxa-oauth], including
+[PKCE][fxa-pkce].
+
+After the OAuth flow is complete, the add-on has an FXA access token and a
+long-living FXA refresh token, and authenticates all requests to the Relay
+server by including an `Authorization: Bearer {fxa-access-token}` header in all
+API requests. The Relay server checks the token against [the FXA OAuth `/verify`
+endpoint][fxa-oauth-token-verify].
+
+This auth scheme can be used by other clients too. E.g., Firefox browser has a
+[`getOAuthToken`][searchfox-getoauthtoken] function which can be used to
+perform the same API authentication as the add-on.
+
+![FXA OAuth Token Authentication Sequence Diagram](api_auth.png)
+
+### TODOs
+* Cache the token verification check so we don't hit FXA on every client request.
+
+[drf]: https://www.django-rest-framework.org/
+[SessionAuthentication]: https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication
+[TokenAuthentication]: https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
+[mdn-webauthflow]: https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/identity/launchWebAuthFlow 
+[fxa-oauth]: https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/api.md
+[fxa-pkce]: https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/pkce.md
+[fxa-oauth-token-verify]: https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/api.md#post-v1verify
+[searchfox-getoauthtoken]: https://searchfox.org/mozilla-central/search?q=symbol:%23getOAuthToken&redirect=false

docs/api_auth.mmd

@@ -0,0 +1,16 @@
+sequenceDiagram
+    participant Extension
+    participant FXA
+    participant Relay
+
+    rect rgba(34, 0, 51, .09)
+    note right of Extension: OAuth2 Flow
+    Extension->>FXA: GET /v1/authorization?...
+    FXA->>Extension: 301 Moved https://{extension-id}.extensions.allizom.org/?...
+    Extension->>FXA: POST /v1/oauth/token/
+    FXA->>Extension: JSON: {token}
+    end
+    Extension->>Relay: GET /api/v1/relayaddresses Authorization: Token {token}
+    Relay->>FXA: POST /v1/oauth/verify {token}
+    FXA->>Relay: 200 OK
+    Relay->>Extension: [{id:, address:, etc.}, {id:, address:, etc.}]