OAuth guide - Login

Author: petak5

README.md

@@ -11,6 +11,7 @@ The documentation is dynamically generated by the server using [Swagger](https:/
 
 - Set up your [environment](#environment)
 - Install [docker-compose](https://docs.docker.com/compose/install/) and do `docker-compose up`
+- for information on how to authenticate for the API, see [authentication](#authentication)
 
 ## Set up guide: The 'bothersome' way
 
@@ -30,6 +31,7 @@ Requirements:
 Run the server:
 - `pipenv run python src/runserver.py`
     - Run with flag `--reset-db` to drop and recreate all tables on start
+- for information on how to authenticate for the API, see [authentication](#authentication)
 
 ## Environment
 
@@ -45,7 +47,22 @@ Run the server:
 
 Your `.env` file should now look something like [example.env](https://github.com/ProgrammingBuddies/programmingbuddies-api/blob/develop/example.env)
 
-### Testing
+## Authentication
+#### Login
+- `/login` route logs in if the user exists in the database, otherwise returns a error message and code in the URL
+- to log in you have to specify several attributes
+    - `account` - currently `github` is the only value that is supported
+    - `username` - your username of account on specified platform in the previous step
+    - `redirect` - url where should you be redirected after authenticating with OAuth
+- put it all these together `https://<url:port>/login?account=<account>&username=<username>&redirect=<redirect>`
+    - e.g.: `https://localhost:5001/login?account=github&username=freddy&redirect=https://localhost:5001` for GitHub account with name `freddy` while developing local with the server hosted on `localhost:5001`
+- you will be redirected to the specified url and get data with it
+    - if the request failed - user was not registered before (user not found in the database), you will get an error message and code
+    - if the request succeeded - you will get a JWT `token` in the URL, that is what you need to authenticate
+- add to your requests `Authorization` header with a value `Bearer <token>` where you replace `<token>` with your `token` acquired in the step above
+#### Register
+
+## Testing
 
 - to run multiple tests just specify the directory which contains them for example `pipenv run pytest tests/`
     - this will run all the tests in the `tests` directory