# Auth API

In addition to the [Zuar Runner API](/api/runner), Zuar Runner users also have
access to the Auth API, which among other things, enables the ability to list,
create, update, and delete users in the Zuar Runner UI.

## Endpoints and Methods

Zuar Runner has [Swagger](https://swagger.io/) documentation at
`https://{runner_url}/auth/docs`. You can see all the Auth API endpoints and
test them using the Swagger UI.

.. image:: assets/auth__swagger.png
   :alt: Zuar Runner Auth API Swagger docs

## Auth API Usage

For more information about API usage and authorization please visit the [Zuar Runner
API help page.](/api/runner/)

### Steps to Create A Zuar Runner User

1. Browse to `https://{runner_url}/auth/docs#/default/create_user_users_post`
2. Expand POST `/users` Create User endpoint
3. Click `Try it out`
4. Edit the input parameters so that the strings represent the appropriate user data
5. `Execute` the Create User command
6. *Optional* but usually necessary, create the user inside of Zuar Runner's
   PostgreSQL database (see link below). A simple command to create a
   PostGreSQL Super User: `CREATE USER "newuser" WITH PASSWORD 'password'
   SUPERUSER CREATEDB;`

.. NOTE::

   A database user is not created. Please consult 
   `PostgreSQL Documentation <https://www.postgresql.org/docs/13/sql-createuser.html>`__ 
   on creating new users.

### Steps to List existing Zuar Runner Users

1. Browse to `https://{runner_url}/auth/docs#/default/list_users_users_get`
2. Expand GET `/users` List Users endpoint
3. Click `Try it out`
4. `Execute` the List Users command
5. The output will contain information for all existing users.

### Steps to Delete a Zuar Runner User

1. Browse to `https://{runner_url}/auth/docs#/default/create_user_users_post`
2. Expand and Execute GET `/users` endpoint to list users per instructions above.
3. Retrieve the ID for the user you wish to delete
4. Expand the DELETE `/users/{user_id}` endpoint
5. Click `Try it out`
6. Enter the ID for the desired user into the user_id field
7. `Execute` the DELETE `/users/{user_id}`
8. *Optional but usually necessary, remove the user from Zuar Runner's PostgreSQL*