mirror of
https://github.com/Govor-team/Govor.git
synced 2026-07-21 19:54:55 +00:00
Artemy
142 lines
4.1 KiB
Markdown
142 lines
4.1 KiB
Markdown
---
|
|
description: >-
|
|
Controller for handling user authentication operations, including registration
|
|
and login, with session management and invite-based registration.
|
|
---
|
|
|
|
# AuthController
|
|
|
|
### Controller Description
|
|
|
|
* **Route**: `api/auth`
|
|
* **Authorize**: Allows anonymous access (`[AllowAnonymous]`).
|
|
|
|
### Endpoints
|
|
|
|
#### <mark style="color:$info;">Register</mark>
|
|
|
|
* **Description**: Registers a new user using a valid invite link and opens a user session, returning an authentication token.
|
|
* **Route**: `[POST] api/auth/register`
|
|
* **HTTP Method**: `POST`
|
|
* **Request**:
|
|
* **Content-Type**: `application/json`
|
|
* **Request Body**: `RegistrationRequest` object with the following structure:
|
|
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"password": "string",
|
|
"inviteLink": "string",
|
|
"deviceInfo": "string"
|
|
}
|
|
```
|
|
* **Responses**:
|
|
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful registration and session creation.
|
|
|
|
```json
|
|
{
|
|
"refreshToken": "string",
|
|
"accessToken": "string"
|
|
}
|
|
```
|
|
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
|
* If model validation fails.
|
|
* If the user already exists: `"Registration failed: user already exists."`
|
|
* If the invite link is invalid: `"Invite link invalid."`
|
|
* If the username is invalid: `"Invalid username: <error_message>"`
|
|
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
|
|
|
```json
|
|
"An unexpected error occurred. Please try again later."
|
|
```
|
|
|
|
#### <mark style="color:$info;">Login</mark>
|
|
|
|
* **Description**: Authenticates an existing user and opens a session, returning an authentication token.
|
|
* **Route**: `[POST] api/auth/login`
|
|
* **HTTP Method**: `POST`
|
|
* **Request**:
|
|
* **Content-Type**: `application/json`
|
|
* **Request Body**: `LoginRequest` object with the following structure:
|
|
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"password": "string",
|
|
"deviceInfo": "string"
|
|
}
|
|
```
|
|
* **Responses**:
|
|
* <mark style="color:$success;">**200 OK**</mark>: Returns the authentication token upon successful login and session creation.
|
|
|
|
```json
|
|
{
|
|
"refreshToken": "string",
|
|
"accessToken": "string"
|
|
}
|
|
```
|
|
* <mark style="color:$danger;">**400 Bad Request**</mark>:
|
|
* If model validation fails.
|
|
* If the user does not exist: `"Login failed: user does not exist."`
|
|
* If the username or password is incorrect: `"Login failed: username or password is incorrect."`
|
|
* <mark style="color:$warning;">**500 Internal Server Error**</mark>: Indicates an unexpected error.
|
|
|
|
```json
|
|
"An unexpected error occurred. Please try again later."
|
|
```
|
|
|
|
### Data Models
|
|
|
|
#### RegistrationRequest
|
|
|
|
* **Description**: Model for registration request data.
|
|
* **Structure**:
|
|
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"password": "string",
|
|
"inviteLink": "string",
|
|
"deviceInfo": "string"
|
|
}
|
|
```
|
|
|
|
#### LoginRequest
|
|
|
|
* **Description**: Model for login request data.
|
|
* **Structure**:
|
|
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"password": "string",
|
|
"deviceInfo": "string"
|
|
}
|
|
```
|
|
|
|
#### RefreshResult
|
|
|
|
* **Description**: Model for refresh token response data.
|
|
* **Structure**:
|
|
|
|
```json
|
|
{
|
|
"refreshToken": "string",
|
|
"accessToken": "string"
|
|
}
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
* **Invalid User ID**: Not applicable (handled by session service).
|
|
* **Invalid Operations**: Registration fails if the user already exists, invite link is invalid, or username is invalid, returning `400 Bad Request`.
|
|
* **Unauthorized Access**: Not applicable (endpoint is `[AllowAnonymous]`).
|
|
* **Unexpected Errors**: General exceptions are caught, logged, and returned as `500 Internal Server Error`.
|
|
|
|
### Logging
|
|
|
|
* Logs successful registration and login events with username and user ID.
|
|
* Logs session opening events with username and user ID.
|
|
* Logs warnings for specific exceptions (e.g., user already exists, invalid invite link, login failures).
|
|
* Logs errors for unexpected exceptions during registration and login.
|