gross authentication notes at the top of every endpoint

doc/api/pages/cookie_tutorial.md

@@ -0,0 +1,3 @@
+One way to access the API is through your browser. Log into metamaps.cc normally, then browse manually to https://metamaps.cc/api/v2/user/current. You should see a JSON description of your own user object in the database. You can browse any GET endpoint by simply going to that URL and appending query parameters in the URI.
+
+To run a POST or DELETE request, you can use the Fetch API. See the example in the next section.

doc/api/pages/getting-started.md

@@ -1,5 +1,3 @@
-[Skip ahead to the endpoints.](#endpoints)
-
 There are three ways to log in: cookie-based authentication, token-based authentication, or OAuth 2.
 
 ### 1. Cookie-based authentication

doc/api/pages/token_tutorial.md

@@ -0,0 +1,25 @@
+If you are logged into the API via another means, you can create a token. Once you have this token, you can append it to a request. For example, opening a private window in your browser and browsing to `https://metamaps.cc/api/v2/user/current?token=...token here...` would show you your current user, even without logging in by another means.
+
+To get a list of your current tokens, you can log in using cookie-based authentication and run the following fetch request in your browser console (assuming the current tab is on some page within the `metamaps.cc` website.
+
+```
+fetch('/api/v2/tokens', {
+  method: 'GET',
+  credentials: 'same-origin' // needed to use the cookie-based auth
+}).then(response => {
+  return response.json()
+}).then(console.log).catch(console.error)
+```
+
+If this is your first time accessing the API, this list wil be empty. You can create a token using a similar method:
+
+```
+fetch('/api/v2/tokens', {
+  method: 'POST',
+  credentials: 'same-origin'
+}).then(response => {
+  return response.json()
+}).then(console.log).catch(console.error)
+```
+
+`payload.data.token` will contain a string which you can use to append to requests to access the API from anywhere.

doc/api/securitySchemes/cookie.raml

@@ -1,3 +1,3 @@
-description: Cookie-based authentication
+description: !include ../pages/cookie_tutorial.md
 type: x-cookie
-displayName: Cookie
+displayName: Secured by cookie-based authentication

doc/api/securitySchemes/token.raml

@@ -1,3 +1,3 @@
-description: Token-based authenticationSecured by OAuth 2.0
+description: !include ../pages/token_tutorial.md
 type: x-token
-displayName: Token-based auth
+displayName: Secured by token-based authentication