Auth Controller Documentation

The AuthController handles user authentication and authorization. It provides endpoints for logging in and inviting users.

For more information on Users, check the Melon User Guide.

Controller Route: /auth/

All routes within the AuthController are prefixed by /auth/.

---

Summary of Endpoints

Endpoint	Method	Description	Authorization
/auth/login	GET	Login with a username and password to obtain a JWT token.	None
/auth/invite	GET	Generate a new invite code for user registration.	Admin
/auth/code-authenticate	GET	Generate a "Server" role JWT using an invite code.	None
/auth/check	GET	Validate a JWT to check if it is still active.	Admin, User, Pass

---

Login

This endpoint handles logging in users with their username and password, returning a JWT token for authenticating future API calls.

Details:

• Endpoint: /auth/login
• Method: GET
• Authorization: None (No token required)

Parameters:

• username (string, required): The username for the account.
• password (string, required): The password for the account.

Responses:

• 200 OK: The username and password match, and a JWT token is returned for use in future requests.
• 401 Unauthorized: The username or password does not match any account on the system.

Example Request:

GET /auth/login?username=johndoe&password=secret

---

Create Invite Code

Generates a four-character invite code that can be used to create new user accounts. This invite code lasts for 10 minutes, during which it can be used to obtain a JWT for account creation. Once an invite code has been used to generate a JWT token, it becomes invalid.

Details:

• Endpoint: /auth/invite
• Method: GET
• Authorization: JWT with Admin Role

Notes:

• Only Admins can generate invite codes.
• The invite code is temporary and will expire after 10 minutes.
• A JWT with the "Server" role can be created from the invite code for the new user registration process by calling auth/code-authenticate

Responses:

• 200 OK: Successfully generated an invite code.
• 401 Unauthorized: The user does not have Admin permissions.
• 408 Request Timeout: There are too many active invite codes, try again later.

Example Request:

GET /auth/invite 
Authorization: Bearer <Admin-JWT>

---

Code Authenticate

This endpoint generates a "Server" role JWT using an invite code. The invite code is invalidated after being used once to create a token.

• Endpoint: /auth/code-authenticate
• Method: GET
• Authorization: None (No token required)

Parameters:

• code (string, required): The four-character invite code.

Notes:

• The JWT created lasts for 10 minutes and is meant to be used with /api/users/create to register a new user.
• The invite code is invalidated after one successful JWT creation.
• Server roles can only be used with api/users/create to create the new user.

Responses:

• 200 OK: A JWT with the "Server" role is returned.
• 401 Unauthorized: The invite code is invalid.

Example Request:

GET /auth/code-authenticate?code=ABCD

---

JWT Authentication Test

This endpoint verifies if the provided JWT token is valid.

• Endpoint: /auth/check
• Method: GET
• Authorization: JWT with Admin, User, or Pass roles

Responses:

• 200 OK: The JWT is valid.
• 401 Unauthorized: The JWT is invalid.

Example Request:

GET /auth/check
Authorization: Bearer <JWT>