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

docs: add refresh/revoke endpoints for token handling

Browse source
This commit is contained in:
Radical 2025-05-02 11:55:25 +02:00
parent 37309f461b
commit 78970bf292
2 changed files with 122 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

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

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