{"id":25448951,"url":"https://github.com/joshuagilgallon/auth-api","last_synced_at":"2025-05-16T08:09:36.551Z","repository":{"id":277683658,"uuid":"931218275","full_name":"JoshuaGilgallon/auth-api","owner":"JoshuaGilgallon","description":"Template authorization API made in Golang","archived":false,"fork":false,"pushed_at":"2025-04-21T00:49:20.000Z","size":99711,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-21T01:27:10.191Z","etag":null,"topics":["auth","authorization","go","golang","mongodb"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JoshuaGilgallon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-11T22:56:46.000Z","updated_at":"2025-04-21T00:49:23.000Z","dependencies_parsed_at":"2025-04-21T01:21:59.759Z","dependency_job_id":"97efb994-78a9-440c-8da0-2c51ad2a0597","html_url":"https://github.com/JoshuaGilgallon/auth-api","commit_stats":null,"previous_names":["joshuagilgallon/auth-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaGilgallon%2Fauth-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaGilgallon%2Fauth-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaGilgallon%2Fauth-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoshuaGilgallon%2Fauth-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoshuaGilgallon","download_url":"https://codeload.github.com/JoshuaGilgallon/auth-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493374,"owners_count":22080127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth","authorization","go","golang","mongodb"],"created_at":"2025-02-17T20:15:56.156Z","updated_at":"2025-05-16T08:09:36.545Z","avatar_url":"https://github.com/JoshuaGilgallon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Authorization API\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Reference](https://pkg.go.dev/badge/golang.org/x/example.svg)](https://pkg.go.dev/)\n![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat\u0026logo=docker\u0026logoColor=white)\n![MongoDB](https://img.shields.io/badge/MongoDB-%234ea94b.svg?style=flat\u0026logo=mongodb\u0026logoColor=white)\n![Swagger](https://img.shields.io/badge/-Swagger-%23Clojure?style=flat\u0026logo=swagger\u0026logoColor=white)\n\n\u003e ⚠️ **Note:** THIS IS CURRENTLY A WORK IN PROGRESS, NOT ALL FEATURES HAVE BEEN IMPLEMENTED YET. THIS VERSION IS BUGGY AND WON'T NECESSARILY WORK.\n\n## Overview\nThis is an **Authorization API** template that I use as a starting point for all my projects. It provides a production-ready authentication system built with **Golang** using the **Gin** framework. Feel free to use and customize it for your projects.\n\n### Features\n- **User and Session Management**\n- **Built in Admin Dashboard with Analytics and Statistics**\n- **MongoDB Integrated** and already setup\n- **Salted Password Hashing**\n- **Email Verification** already setup!\n- **Multi-Factor Authentication (MFA) Support** via Email, but infrastructure allows for easy expansion.\n- **Rate Limiting \u0026 Brute Force Protection** plus a lot of other security precautions\n- **Swagger Documentation for Debugging** (Accessible at `/docs/index.html`)\n- **and much much more!**\n\n---\n\n## Important Notes\nHere are some important points you need to consider/know when using this template\n\n### Liability Disclaimer\n\n⚠️ This template is provided **as is**, without any warranties or guarantees. I am **not responsible or liable** for any issues, security vulnerabilities, data loss, or damages that may occur while using, modifying, or deploying this template. Use it at your own risk, and make sure to review and customize it according to your project's security and operational requirements.\n\n### MongoDB setup\nThe API is currently set up to recieve requests from either a local MongoDB database instance or a remote one. Running it locally will require further installation and setup from the official MongoDB site. If you are using it remotely, for example Atlas, copy and paste your URI into the .env file (you may need to create one, the instruction for how to set it up is in the installation section. Docker will NOT install MongoDB, therefore you either need to download it yourself or create a remote instance.\n\n### Debug mode\nThe API is set to debug mode by default and will need to be manually configured and removed before pushing to production.\n\n---\n\n## Setup\n\n### Prerequisites\n\n[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white)](https://www.docker.com/products/docker-desktop/)\n[![MongoDB](https://img.shields.io/badge/MongoDB-%234ea94b.svg?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)](https://www.mongodb.com/)\n\n### Create an environment file\nCreate your .env file in the root directory of the auth-api folder.\nSet it up as so:\n\n```env\nDATABASE_URI=\u003cyour database uri\u003e\nUSER_AES_KEY=\u003cyour aes-256 encryption key\u003e\nRESEND_API_KEY=\u003cyour api key from resend\u003e\nROOT_ADMIN_USER=\u003cadmin_username_here\u003e\nROOT_ADMIN_PASSWORD=\u003cadmin_password_here\u003e\n\nBASE_URL=\u003cthe base url of your front end, e.g. example.com\u003e\nEMAIL_REDIRECT_BASE=\u003cthe base url for email redirects, e.g. example.com/email/redirect/token:\u003e\n```\n\nMake sure you put your unique AES encryption key **INSIDE THE ENVIRONMENT FILE** and not inside the code. To generate a random secure key, visit [this website](https://generate-random.org/encryption-key-generator) - Leaving everything on default values.\n\nFor the ROOT ADMIN user section; this will be the account that you log in to that will manage all the other admin users. It will have the highest clearance level. Make sure NOT to share the login details of this account anywhere. Logging into the admin portal through this account is the only way you can create new admin users.\n\nFor the EMAIL REDIRECT BASE section; you will need to have a route defined on your front end which will allow a param to be placed after it continuing setup. For example, for ``test.com/v/:code`` - you would put ``test.com/v/`` as the env variable.\n\n### Quick Start\n\n```sh\n# Build the docker images\nmake -f deploy/Makefile docker-build\n\n# Run the docker images\nmake -f deploy/Makefile docker-run\n```\n\nThis will run the worker process in the background, and start running the main API process in the current terminal.\n\nTo view the logs for the worker process, go to a different terminal and run:\n\n```sh\ndocker logs -f auth-worker\n```\n\n---\n\n## How it works  \nThis section will deep-dive into explaining every part of the API and how it works.\n\n---\n\n### Users\nWhen a user is created the following will happen:\n\n1. **Endpoint Called**\n2. **User Password Hashed**\n3. **Information sent to database for storage**\n\n---\n\n### Session Handling\n\nSession handling ensures users stay logged in while keeping their accounts secure. Our implementation follows **best practices using Access Tokens and Refresh Tokens** for authentication.  \n\n#### **How It Works**  \n\n1. **User Logs In**  \n   - The server verifies the user's credentials.  \n   - It returns **two tokens**:  \n     - **Access Token** – Short-lived (30 min), used for authentication in API requests.  \n     - **Refresh Token** – Long-lived (7 days), stored in an **HTTP-only Secure Cookie**.  \n\n2. **Access Token Usage**  \n   - The client stores the **Access Token in memory** (e.g., React state, Vuex, Redux).  \n   - All API requests include:  \n     ```\n     Authorization: Bearer \u003caccess_token\u003e\n     ```\n   - The server **validates** the token before processing the request.  \n\n3. **Token Expiry \u0026 Renewal**  \n   - When the **Access Token expires (after 30 min)**, API requests fail with `401 Unauthorized`.  \n   - The client **automatically requests a new Access Token** using the **Refresh Token**.  \n   - The browser **sends the Refresh Token in an HTTP-only cookie** to `/refresh`.  \n   - If the Refresh Token is valid, the server issues a **new Access Token**.  \n\n4. **Session Expiry \u0026 Logout**  \n   - If the Refresh Token is expired (after 7 days) or revoked, the user is logged out.  \n   - The client must **log in again** to get a new session.\n\n---\n\n## Contributing\n\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\nFeel free to contribute by submitting pull requests or reporting issues. Any suggestions for improvement are welcome!\n\n---\n\n## License\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThis project is open-source and available under the [MIT License](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003csup\u003eP.S. This is one of my first go projects so don't expect it to be too good.\u003c/sup\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuagilgallon%2Fauth-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshuagilgallon%2Fauth-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuagilgallon%2Fauth-api/lists"}