From 3d111b35e3adb61b91a02100da190077dcc40b2a Mon Sep 17 00:00:00 2001 From: Radical Date: Fri, 2 May 2025 11:54:04 +0200 Subject: [PATCH] docs: match login and register to backend --- API/client-server/v1/auth/login.md | 64 +++++++++++++++++++++ API/client-server/v1/{ => auth}/register.md | 52 ++++++++++------- API/client-server/v1/login.md | 57 ------------------ 3 files changed, 95 insertions(+), 78 deletions(-) create mode 100644 API/client-server/v1/auth/login.md rename API/client-server/v1/{ => auth}/register.md (58%) delete mode 100644 API/client-server/v1/login.md diff --git a/API/client-server/v1/auth/login.md b/API/client-server/v1/auth/login.md new file mode 100644 index 0000000..d84d598 --- /dev/null +++ b/API/client-server/v1/auth/login.md @@ -0,0 +1,64 @@ +POST /v1/auth/login + +--- + +Authenticates the user, and issues an access token for future requests. + +--- + +## Request + +| Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------------ | +| username | string | **Required**: Can be the Gorb ID or email of the user trying to log in | +| password | string | **Required**: The user's password in SHA3-384. | +| device_name | string | **Required**: Name to help the user identify the device in their session list. | + +```json +{ + "user_id": "radial_4740", + "password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c", + "device_name": "Laptop" +} +``` + +--- + +## Responses + +| Status | Description | +|--------|-------------------------------------------------| +| 200 | Authentication successful. | +| 400 | The post request included poorly formated data. | +| 403 | Part of the cridentials are invalid. | +| 500 | An unhandled error occured. | + +--- + +### 200 + +| Name | Type | Description | +| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| access_token | string | **Required**: The access token that will be used for further authentication. | +| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | + +```json +{ + "access_token": "85b2afece430e0e924f2d4277324c868", + "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749" +} +``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` diff --git a/API/client-server/v1/register.md b/API/client-server/v1/auth/register.md similarity index 58% rename from API/client-server/v1/register.md rename to API/client-server/v1/auth/register.md index 2b88b0f..fb950a9 100644 --- a/API/client-server/v1/register.md +++ b/API/client-server/v1/auth/register.md @@ -1,4 +1,4 @@ -POST /v1/register +POST /v1/auth/register --- @@ -8,18 +8,18 @@ Registers the user, and issues an access token for future requests. ## Request -| Name | Type | Description | -|-------------|--------|-----------------------------------------------------------------------------------------------------------------| -| identifier | string | **Required** User's desired ID. | -| email | string | **Required** User's email. | -| password | string | **Required**: The user's password (we need to figure out how exactly we're hashing + salting it on the client). | -| device_name | string | Name to help the user identify the device in their session list. | +| Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------------ | +| identifier | string | **Required** User's desired ID. | +| email | string | **Required** User's email. | +| password | string | **Required**: The user's password in SHA3-384. | +| device_name | string | **Required**: Name to help the user identify the device in their session list. | ```json { "identifier": "radial_4740", "email": "radial_4740@yahoo.com", - "password": "9r89mhs4czu4", + "password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c", "device_name": "Laptop" } ``` @@ -39,21 +39,15 @@ Registers the user, and issues an access token for future requests. ### 200 -| Name | Type | Description | -|---------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------| -| access_token | string | **Required**: The JWT access token that will be used for further authentication. | -| user_id | string | **Required**: The account's local gorb ID. | -| uuid | string | **Required**: The account's UUID. | -| expires_in | int | How many seconds until the token expires and is invalidated. | -| refresh_token | string | The JWT refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | +| Name | Type | Description | +| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| access_token | string | **Required**: The access token that will be used for further authentication. | +| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | ```json { - "access_token": "13aa5fe2ae5874fb9616e68c25632a146552584ac238a3e4ede08174fbfc4f45", - "user_id": "radial_4740", - "uuid": "dcb445f1-16e7-4cd9-ac19-af07acaeb865", - "expires_in": 86400, - "refresh_token": "8556a85b8912a78572cd67b21350e188039f656a0781dab20fab7b72a11d2a93" + "access_token": "85b2afece430e0e924f2d4277324c868", + "refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749" } ``` @@ -62,12 +56,13 @@ Registers the user, and issues an access token for future requests. ### 403 | Name | Type | Description | -|-----------------------------|------|--------------------------------------------------------------------------------| +| --------------------------- | ---- | ------------------------------------------------------------------------------ | | signups_enabled | bool | Does the server have signups enabled? | | gorb_id_valid | bool | Is the given gorb ID even valid? | | gorb_id_available | bool | Is the given gorb ID available? | | email_valid | bool | Is the given email valid? | | email_available | bool | Is the given email available? | +| password_hashed | bool | Is the password hashed using SHA3-384? | | password_minimum_length | bool | Is the given password long enough? | | password_special_characters | bool | If enforced by the server, is there enough special characters in the password? | | password_letters | bool | If enforced by the server, is there enough letters in the password? | @@ -80,9 +75,24 @@ Registers the user, and issues an access token for future requests. "gorb_id_available": true, "email_valid": true, "email_available": false, + "password_hashed": true, "password_minimum_length": true, "password_special_characters": false, "password_letters": true, "password_numbers": true } ``` + +--- + +### 500 + +| Name | Type | Description | +| ----- | ------ | -------------------------------- | +| error | string | The error the server encountered | + +```json +{ + "error": "Something went wrong!", +} +``` diff --git a/API/client-server/v1/login.md b/API/client-server/v1/login.md deleted file mode 100644 index b4d8c17..0000000 --- a/API/client-server/v1/login.md +++ /dev/null @@ -1,57 +0,0 @@ -POST /v1/login - ---- - -Authenticates the user, and issues an access token for future requests. - ---- - -## Request - -| Name | Type | Description | -|-------------|--------|-----------------------------------------------------------------------------------------------------------------| -| user_id | string | User's gorb ID. One of identifier and email **must** be implemented. | -| email | string | User's email. One of identifier and email **must** be implemented. | -| password | string | **Required**: The user's password (we need to figure out how exactly we're hashing + salting it on the client). | -| device_name | string | Name to help the user identify the device in their session list. | - -```json -{ - "user_id": "radial_4740", - "password": "9r89mhs4czu4", - "device_name": "Laptop" -} -``` - ---- - -## Responses - -| Status | Description | -|--------|-------------------------------------------------| -| 200 | Authentication successful. | -| 400 | The post request included poorly formated data. | -| 403 | Part of the cridentials are invalid. | -| 500 | An unhandled error occured. | - ---- - -### 200 - -| Name | Type | Description | -|---------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------| -| access_token | string | **Required**: The access token that will be used for further authentication. | -| user_id | string | **Required**: The account's local gorb ID. | -| uuid | string | **Required**: The account's UUID. | -| expires_in | int | How many seconds until the token expires and is invalidated. | -| refresh_token | string | The refresh token that will be used to refresh the access token. Required for avoiding users having to log in after access token expiration. | - -```json -{ - "access_token": "35e404d160b0eac766cb85cf513670baa627d1e918c4813c3f099e31de300b63", - "user_id": "radial_4740", - "uuid": "dcb445f1-16e7-4cd9-ac19-af07acaeb865", - "expires_in": 86400, - "refresh_token": "d9ce91b7b643d5580ea605ad09ba1e13aef704c412194c00c592b96a62049587" -} -```