gorb/specifications
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request 'Implement changes from backend' (#1) from backend into main

Browse source 
Reviewed-on: #1
This commit is contained in:
Radical 2025-05-02 19:39:21 +00:00
commit d8a9b79df2
6 changed files with 219 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

64
API/client-server/v1/auth/login.md Normal file
View file

@ -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!",
}
```

60
API/client-server/v1/auth/refresh.md Normal file
View file

@ -0,0 +1,60 @@
POST /v1/auth/refresh
---
Reauthenticates the user using the refresh token, and issues an access token for future requests.
---
## Request
| Name | Type | Description |
| ------------- | ------ | --------------------- |
| refresh_token | string | User's refresh token. |
```json
{
"refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749",
}
```
---
## 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. NOTE: This endpoint returns the same refresh_token if it was generated less than 23 days ago. |
```json
{
"access_token": "85b2afece430e0e924f2d4277324c868",
"refresh_token": "aeb343482fcee3a293e887f5dc840ea8b0fc6b54a26c2584a95a5bc91ff4a749"
}
```
---
### 500
| Name | Type | Description |
| ----- | ------ | -------------------------------- |
| error | string | The error the server encountered |
```json
{
"error": "Something went wrong!",
}
```

52
API/client-server/v1/register.md → API/client-server/v1/auth/register.md
View file

@ -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!",
}
```

62
API/client-server/v1/auth/revoke.md Normal file
View file

@ -0,0 +1,62 @@
POST /v1/auth/revoke
---
Revokes authenticated refresh/access tokens owned by the user.
---
## Request
| Name | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------- |
| access_token | string | User's access token to validate the session. |
| password | string | SHA3-384 of user password to ensure its the user trying to do this and not someone who has the access token |
| device_name | string | device_name that should be removed from the list of logins (NOTE: Removes all devices with the same name) |
```json
{
"access_token": "85b2afece430e0e924f2d4277324c868",
"password": "f324cbd421326a2abaedf6f395d1a51e189d4a71c755f531289e519f079b224664961e385afcc37da348bd859f34fd1c",
"device_name": "Laptop"
}
```
---
## Responses
| Status | Description |
|--------|-------------------------------------------------|
| 200 | Deletion 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 |
| ------- | ---- | --------------------------------------------------------------------- |
| deleted | bool | Returns true if the refresh/access token(s) were successfully deleted |
```json
{
"deleted": true
}
```
---
### 500
| Name | Type | Description |
| ----- | ------ | -------------------------------- |
| error | string | The error the server encountered |
```json
{
"error": "Something went wrong!",
}
```

4
API/client-server/v1/friend-request.md
View file

@ -9,7 +9,7 @@ Sends a friend request to the given user. Friend requests can be accepted by hav
## Request
| Name | Type | Description |
|--------------|--------|------------------------------------------------------------------------------------------------|
| ------------ | ------ | ---------------------------------------------------------------------------------------------- |
| access_token | string | **Required**: The user's auth token. |
| uuid | string | **Required**: The UUID of the user they want to befriend. |
| server | string | The instance that user is on, can be left out if it's a local friend request. |
@ -17,7 +17,7 @@ Sends a friend request to the given user. Friend requests can be accepted by hav
```json
{
"access_token": "gwLhWXD9wrqL3DwxXZ0VHUeOjr8am1yO",
"access_token": "85b2afece430e0e924f2d4277324c868",
"uuid": "dcb445f1-16e7-4cd9-ac19-af07acaeb865",
"server": "gorb.app",
"message": "Heyo, Kira here"

57
API/client-server/v1/login.md
View file

@ -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"
}
```