wip(markdown): More work on backend docs
This commit is contained in:
Joost De Cock
parent
749516af8e
commit
beae5e9b09
9 changed files with 467 additions and 25 deletions
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
title: Confirm a User
|
||||
title: Confirm an account
|
||||
---
|
||||
|
||||
Confirms a newly created User.
|
||||
Confirms a newly created User account.
|
||||
If confirmation is successful this will also result in a (passwordless) login.
|
||||
|
||||
## Endpoints
|
||||
|
||||
Confirming a new User is possible via this endpoint:
|
||||
Confirming a new User account is possible via this endpoint:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
|
|
@ -18,7 +18,7 @@ Confirming a new User is possible via this endpoint:
|
|||
## Request url
|
||||
|
||||
The url should contain the confirmation ID that was E-mailed to the E-mail
|
||||
address used for the signup. It replaces the `:id` placeholder in the
|
||||
address used for the signup. It replaces the `:id` placeholder in the
|
||||
[endpoint listed above](#endpoints).
|
||||
|
||||
## Request body
|
||||
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
title: Create a User
|
||||
title: Create an account
|
||||
---
|
||||
|
||||
Creates a new User. The User account will remain inactive
|
||||
until [it is confirmed](/reference/backend/api/users/confirm).
|
||||
Creates a new User account. The User account will remain inactive
|
||||
until [it is confirmed](/reference/backend/api/account/confirm).
|
||||
|
||||
## Endpoints
|
||||
|
||||
Creating a new User is possible via this endpoint:
|
||||
Creating a new User account is possible via this endpoint:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
|
|
@ -1,8 +1,12 @@
|
|||
---
|
||||
title: Users
|
||||
title: Account
|
||||
---
|
||||
|
||||
A User holds the account data for a FreeSewing user.
|
||||
From an end-user's point of view, their account holds all of their data. From
|
||||
an API point of view, these endpoints deal with data in the User table.
|
||||
|
||||
As the endpoints typically use `/account` we tend to use _account_ more often
|
||||
than _user_.
|
||||
|
||||
## Endpoints
|
||||
|
||||
113
markdown/dev/reference/backend/api/account/login/en.md
Normal file
113
markdown/dev/reference/backend/api/account/login/en.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
title: Login
|
||||
---
|
||||
|
||||
Login as a User with username and password, and optional MFA token.
|
||||
|
||||
## Endpoints
|
||||
|
||||
Password-based login is possible via this endpoint:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method post /> | `/login` | None |
|
||||
|
||||
<Note compact>This endpoint requires no authentication</Note>
|
||||
|
||||
## Request body
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `username` | `string` | The E-mail address of the User |
|
||||
| `password` | `boolean`| The language code for the User |
|
||||
| `token` | `boolean`| The MFA token |
|
||||
|
||||
<Note compact>An MFA token is required (only) when the User enabled MFA</Note>
|
||||
|
||||
## Response status codes
|
||||
|
||||
Possible status codes for these endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="201"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | authentication failed |
|
||||
| <StatusCode status="403"/> | MFA token missing |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
## Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| ------------------- | -------- | ----------- |
|
||||
| `result` | String | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `token` | String | A JSON web token (JWT) token to authenticate with |
|
||||
| `account.id` | Number | The ID of the User |
|
||||
| `account.bio` | String | The bio of the User |
|
||||
| `account.consent` | Number | The consent given by the User |
|
||||
| `account.control` | Number | The control desired by the User |
|
||||
| `account.createdAt` | String | Date string indicating the moment the User was created |
|
||||
| `account.email` | String | The E-mail address currently tied to the User |
|
||||
| `account.github` | String | The Github username of the User |
|
||||
| `account.img` | String | The URL to the image stored with this User |
|
||||
| `account.imperial` | Boolean| Whether or not the User prefers imperial units |
|
||||
| `account.initial` | String | The E-mail address that the User was created with |
|
||||
| `account.language` | String | The language preferred by the user |
|
||||
| `account.lastLogin` | String | Date string indicating them moment the User last logged in |
|
||||
| `account.mfaEnabled`| Boolean| Whether or not the User has MFA enabled |
|
||||
| `account.newsletter`| Boolean| Whether or not the User is subscribed to the FreeSewing newsletter |
|
||||
| `account.patron` | Number | The level of patronage the user provides to FreeSewing |
|
||||
| `account.role` | String | The role of the User |
|
||||
| `account.status` | Number | The status of the user |
|
||||
| `account.updatedAt` | String | Date string indicating the last time the User was updated |
|
||||
| `account.username` | String | The username of the User |
|
||||
| `account.lusername` | String | A lowercased version of the username of the User |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const signup = await axios.post(
|
||||
'https://backend.freesewing.org/signup',
|
||||
{
|
||||
username: "jimmy",
|
||||
language: "I like big bewbs and I just can't lie",
|
||||
token: 231586
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5c...truncated",
|
||||
"account": {
|
||||
"id": 14,
|
||||
"bio": "",
|
||||
"consent": 1,
|
||||
"control": 1,
|
||||
"createdAt": "2022-11-19T18:15:22.642Z",
|
||||
"email": "test_54c6856275aaa8a1@freesewing.dev",
|
||||
"github": "",
|
||||
"img": "https://freesewing.org/avatar.svg",
|
||||
"imperial": false,
|
||||
"initial": "test_54c6856275aaa8a1@freesewing.dev",
|
||||
"language": "en",
|
||||
"lastLogin": "2022-11-19T18:15:22.668Z",
|
||||
"mfaEnabled": false,
|
||||
"newsletter": false,
|
||||
"patron": 0,
|
||||
"role": "user",
|
||||
"status": 1,
|
||||
"updatedAt": "2022-11-19T18:15:22.668Z",
|
||||
"username": "jimmy",
|
||||
"lusername": "jimmy"
|
||||
}
|
||||
}
|
||||
```
|
||||
214
markdown/dev/reference/backend/api/account/mfa/en.md
Normal file
214
markdown/dev/reference/backend/api/account/mfa/en.md
Normal file
|
|
@ -0,0 +1,214 @@
|
|||
---
|
||||
title: MFA
|
||||
---
|
||||
|
||||
Enable of disable Multi-Factor Authentication (MFA) on the User account.
|
||||
|
||||
- [Setup MFA](#setup-mfa)
|
||||
- [Confirm MFA](#confirm-mfa)
|
||||
- [Disable MFA](#disable-mfa)
|
||||
|
||||
## Endpoints
|
||||
|
||||
Enabling, confirming, and disabling MFA is all possible via this endpoint:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method post /> | `/account/mfa/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
|
||||
| <Method post /> | `/account/mfa/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
|
||||
|
||||
## Setup MFA
|
||||
|
||||
### Request body
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `mfa` | `boolean`| Set to `true` to enable MFA |
|
||||
|
||||
### Response status codes
|
||||
|
||||
Possible status codes for this endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="201"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | authentication failed |
|
||||
| <StatusCode status="403"/> | access denied |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
### Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| -------------- | -------- | ----------- |
|
||||
| `result` | String | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `mfa.secret` | String | The shared secret for generating one-time password (OTP) tokens |
|
||||
| `mfa.otpauth` | String | The OTP Auth uri that is encoded in the QR code |
|
||||
| `mfa.qrcode` | String | SVG to display a QR code with the otpauth uri encoded |
|
||||
|
||||
<Tip>
|
||||
##### Styling the SVG
|
||||
The SVG returned by the backend uses `currentColor` for the QR code, so you can
|
||||
style it with CSS if you embed it in the page.
|
||||
</Tip>
|
||||
|
||||
### Example request
|
||||
|
||||
```js
|
||||
const mfa = await axios.post(
|
||||
'https://backend.freesewing.org/account/mfa/jwt',
|
||||
{ mfa: true },
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"mfa": {
|
||||
"secret": "KBTSKUKRDJPEGCZK",
|
||||
"otpauth": "otpauth://totp/FreeSewing:user-294?secret=KBTSKUKRDJPEGCZK&period=30&digits=6&algorithm=SHA1&issuer=FreeSewing",
|
||||
"qrcode": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 53 53\" shape-rendering=\"crispEdges\"><path fill=\"none\" d=\"M0 0h53v53H0z\"/><path stroke=\"currentColor\" d=\"M4 4.5h7m1 0h1m3 0h1m1 0h3m2 0h1m1 0h1m1 0h1m1 0h2m1 0h5m3 0h1m1 0h7M4 5.5h1m5 0h1m1 0h4m1 0h2m4 0h1m2 0h3m3 0h1m2 0h2m2 0h1m2 0h1m5 0h1M4 6.5h1m1 0h3m1 0h1m1 0h2m1 0h3m4 0h2m1 0h2m3 0h4m2 0h1m2 0h1m2 0h1m1 0h3m1 0h1M4 7.5h1m1 0h3m1 0h1m7 0h1m6 0h3m3 0h1m1 0h1m5 0h2m1 0h1m1 0h3m1 0h1M4 8.5h1m1 0h3m1 0h1m1 0h1m1 0h3m1 0h3m1 0h8m3 0h1m2 0h1m1 0h3m1 0h1m1 0h3m1 0h1M4 9.5h1m5 0h1m7 0h1m1 0h3m1 0h1m3 0h1m2 0h3m1 0h1m1 0h1m4 0h1m5 0h1M4 10.5h7m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h1m1 0h7M14 11.5h2m3 0h4m1 0h1m3 0h4m2 0h1m1 0h3m1 0h1M4 12.5h1m2 0h6m1 0h2m6 0h1m1 0h5m1 0h1m1 0h2m1 0h1m3 0h1m1 0h1m2 0h1m1 0h3M5 13.5h3m3 0h2m1 0h2m5 0h2m1 0h2m2 0h5m1 0h2m2 0h1m2 0h4m1 0h2M5 14.5h1m1 0h2m1 0h1m5 0h1m2 0h1m2 0h1m1 0h3m10 0h2m2 0h1m3 0h1m1 0h2M5 15.5h2m2 0h1m2 0h4m1 0h1m4 0h3m2 0h1m2 0h3m1 0h1m2 0h4m2 0h6M5 16.5h1m4 0h1m2 0h4m1 0h3m1 0h2m1 0h1m3 0h4m2 0h1m2 0h2m3 0h2M5 17.5h3m1 0h1m1 0h1m3 0h2m2 0h3m5 0h2m2 0h1m2 0h1m2 0h1m1 0h2m1 0h2m2 0h1M4 18.5h2m1 0h2m1 0h2m4 0h5m5 0h1m2 0h5m1 0h1m5 0h3m3 0h2M4 19.5h1m1 0h2m3 0h2m2 0h1m1 0h1m1 0h1m1 0h2m3 0h1m2 0h3m1 0h1m1 0h1m1 0h2m1 0h1m1 0h3m1 0h3M6 20.5h1m1 0h3m1 0h1m2 0h1m1 0h1m1 0h4m1 0h1m3 0h1m1 0h3m2 0h3m1 0h1m1 0h1m1 0h1m2 0h1M4 21.5h1m1 0h2m1 0h1m3 0h5m2 0h1m4 0h2m1 0h1m1 0h2m2 0h1m4 0h2m3 0h2m1 0h2M4 22.5h5m1 0h2m3 0h1m1 0h1m3 0h2m9 0h3m1 0h1m2 0h1m3 0h1m2 0h2M4 23.5h1m1 0h1m1 0h1m3 0h1m2 0h1m2 0h1m1 0h2m1 0h2m2 0h4m1 0h3m8 0h2M4 24.5h1m1 0h9m2 0h1m1 0h2m1 0h7m2 0h1m3 0h3m1 0h7M6 25.5h1m1 0h1m3 0h1m1 0h4m1 0h3m2 0h1m3 0h1m1 0h2m3 0h1m3 0h2m3 0h4M4 26.5h1m1 0h1m1 0h1m1 0h1m1 0h2m2 0h1m1 0h1m1 0h1m3 0h1m1 0h1m1 0h3m1 0h2m3 0h4m1 0h1m1 0h3m1 0h1M4 27.5h1m1 0h1m1 0h1m3 0h1m5 0h1m2 0h1m1 0h2m3 0h2m3 0h3m1 0h1m1 0h2m3 0h1m1 0h2M5 28.5h1m2 0h8m2 0h2m4 0h5m1 0h1m1 0h4m4 0h5M8 29.5h1m2 0h2m3 0h1m2 0h1m2 0h1m2 0h2m1 0h1m1 0h2m3 0h1m1 0h1m2 0h2m1 0h1m3 0h1M4 30.5h3m1 0h1m1 0h1m1 0h1m1 0h1m3 0h1m2 0h1m1 0h3m4 0h1m1 0h2m2 0h1m2 0h1m1 0h2m2 0h2M4 31.5h1m1 0h1m2 0h1m2 0h1m1 0h1m2 0h3m1 0h1m5 0h4m1 0h1m1 0h1m1 0h5m2 0h1m2 0h1M6 32.5h1m2 0h3m2 0h1m1 0h2m1 0h1m1 0h2m2 0h1m2 0h1m3 0h1m4 0h1m2 0h3m1 0h1M4 33.5h1m1 0h2m1 0h1m2 0h1m2 0h1m1 0h1m1 0h3m3 0h3m2 0h1m2 0h1m4 0h2m3 0h2m2 0h2M7 34.5h1m2 0h5m1 0h5m1 0h2m1 0h1m2 0h1m4 0h4m2 0h1m2 0h1m1 0h2m1 0h1M4 35.5h2m2 0h1m2 0h1m1 0h1m1 0h1m2 0h8m2 0h2m1 0h4m3 0h2m1 0h1m5 0h2M9 36.5h5m1 0h5m3 0h1m1 0h1m1 0h5m5 0h1m7 0h2M5 37.5h2m2 0h1m2 0h3m6 0h1m1 0h2m3 0h1m1 0h2m1 0h3m2 0h5m4 0h1M8 38.5h1m1 0h1m1 0h3m2 0h1m3 0h2m1 0h1m1 0h1m2 0h1m1 0h1m3 0h1m2 0h2m1 0h5M5 39.5h4m5 0h1m2 0h4m3 0h1m2 0h4m1 0h1m2 0h2m3 0h1m1 0h1m1 0h2M4 40.5h1m2 0h2m1 0h1m1 0h2m4 0h12m3 0h1m1 0h1m2 0h7m3 0h1M12 41.5h1m1 0h3m1 0h3m3 0h1m3 0h1m2 0h1m3 0h1m2 0h1m1 0h1m3 0h1m1 0h2M4 42.5h7m1 0h1m2 0h4m1 0h3m1 0h1m1 0h1m1 0h2m1 0h1m2 0h2m4 0h1m1 0h1m1 0h1m1 0h2M4 43.5h1m5 0h1m1 0h1m1 0h1m1 0h2m1 0h3m2 0h1m3 0h3m2 0h6m1 0h1m3 0h3M4 44.5h1m1 0h3m1 0h1m1 0h1m2 0h2m1 0h2m1 0h1m2 0h6m3 0h1m3 0h1m2 0h6m2 0h1M4 45.5h1m1 0h3m1 0h1m1 0h5m3 0h2m1 0h3m1 0h3m3 0h3m1 0h2m4 0h2m1 0h1m1 0h1M4 46.5h1m1 0h3m1 0h1m3 0h5m3 0h5m1 0h2m1 0h2m2 0h1m1 0h1m1 0h3m1 0h1m1 0h4M4 47.5h1m5 0h1m2 0h1m2 0h1m1 0h1m2 0h1m4 0h2m2 0h1m3 0h2m1 0h3m1 0h3m2 0h3M4 48.5h7m1 0h5m2 0h3m3 0h1m2 0h1m1 0h3m1 0h2m2 0h1m1 0h1m1 0h2m1 0h1\"/></svg>\n"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Confirm MFA
|
||||
|
||||
To confirm the MFA, we need to provide an MFA token to ensure the user can
|
||||
generate them.
|
||||
|
||||
### Request body
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `mfa` | `boolean`| Must be set to `true` to confirm MFA |
|
||||
| `secret` | `boolean`| The secret returned when setting up MFA |
|
||||
| `token` | `boolean`| Must be set to `true` to confirm MFA |
|
||||
|
||||
### Response status codes
|
||||
|
||||
Possible status codes for this endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="201"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | authentication failed |
|
||||
| <StatusCode status="403"/> | access denied |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
### Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| -------------- | -------- | ----------- |
|
||||
| `result` | String | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
|
||||
### Example request
|
||||
|
||||
```js
|
||||
import { authenticator } from '@otplib/preset-default'
|
||||
|
||||
const confirm = await axios.post(
|
||||
'https://backend.freesewing.org/account/mfa/jwt',
|
||||
{
|
||||
mfa: true,
|
||||
secret: mfa.secret,
|
||||
token: authenticator.generate(mfa.secret)
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
}
|
||||
```
|
||||
## Disable MFA
|
||||
|
||||
To disable MFA, you need to provide both the account password and a valid token.
|
||||
|
||||
### Request body
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `mfa` | `boolean`| Must be set to `false` to disable MFA |
|
||||
| `password` | `boolean`| The User's password |
|
||||
| `token` | `boolean`| Must be set to `true` to confirm MFA |
|
||||
|
||||
### Response status codes
|
||||
|
||||
Possible status codes for this endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="201"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | authentication failed |
|
||||
| <StatusCode status="403"/> | access denied |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
### Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| -------------- | -------- | ----------- |
|
||||
| `result` | String | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
|
||||
### Example request
|
||||
|
||||
```js
|
||||
import { authenticator } from '@otplib/preset-default'
|
||||
|
||||
const confirm = await axios.post(
|
||||
'https://backend.freesewing.org/account/mfa/jwt',
|
||||
{
|
||||
mfa: false,
|
||||
password: "I like big bewbs and I just can't lie",
|
||||
token: authenticator.generate(mfa.secret)
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
}
|
||||
```
|
||||
|
||||
126
markdown/dev/reference/backend/api/account/update/en.md
Normal file
126
markdown/dev/reference/backend/api/account/update/en.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
title: Update account
|
||||
---
|
||||
|
||||
Updates an existing User account.
|
||||
|
||||
## Access control
|
||||
|
||||
- [Permission level](/reference/backend/api/rbac) `4` or higher is required to update your own User account
|
||||
- [Permission level](/reference/backend/api/rbac) `8` is required to update **another user's** account
|
||||
|
||||
## Endpoints
|
||||
|
||||
Updating an existing User account is possible via these endpoints:
|
||||
|
||||
| Method | Path | Authentication |
|
||||
| --------: | :--- | :------------- |
|
||||
| <Method put /> | `/account/jwt` | [JSON Web Token](/reference/backend/api/authentication#jwt-authentication) |
|
||||
| <Method put /> | `/account/key` | [API Key & Secret](/reference/backend/api/authentication#key-authentication) |
|
||||
|
||||
## Request body
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------: | :------- | :---------- |
|
||||
| `bio` | `string` | The User's bio |
|
||||
| `consent` | `string` | A number that indicates [the consent given by the user](/reference/backend/api/account#the-consent-field-is-about-data-protection) |
|
||||
| `control` | `string` | A number that indicates [the level of control the user prefers](/reference/backend/api/account#the-control-field-is-about-keeping-it-simple) |
|
||||
| `github` | `string` | The User's username on Github |
|
||||
| `imperial` | `boolean`| Whether or not the User prefers imperial units |
|
||||
| `newsletter`| `boolean`| Whether this Person prefers imperial measurements (`true`) or not (`false`) |
|
||||
| `img` | `string` | An image [data-uri][duri] to store with this Person |
|
||||
| `password` | `string` | The (new) password for the User |
|
||||
| `username` | `string` | The (new) username for the User |
|
||||
|
||||
## Response status codes
|
||||
|
||||
Possible status codes for these endpoints are:
|
||||
|
||||
| Status code | Description |
|
||||
| ----------: | :---------- |
|
||||
| <StatusCode status="200"/> | success |
|
||||
| <StatusCode status="400"/> | the request was malformed |
|
||||
| <StatusCode status="401"/> | the request lacks authentication |
|
||||
| <StatusCode status="403"/> | authentication failed |
|
||||
| <StatusCode status="500"/> | server error |
|
||||
|
||||
<Note>
|
||||
If the status code is not <StatusCode status="200" /> the `error` property
|
||||
in the response body should indicate the nature of the problem.
|
||||
</Note>
|
||||
|
||||
## Response body
|
||||
|
||||
| Value | Type | Description |
|
||||
| ------------------- | -------- | ----------- |
|
||||
| `result` | String | Either `success` or `error` |
|
||||
| `error` | String | Will give info on the nature of the error. Only set if an error occured. |
|
||||
| `account.id` | Number | The ID of the User |
|
||||
| `account.bio` | String | The bio of the User |
|
||||
| `account.consent` | Number | The consent given by the User |
|
||||
| `account.control` | Number | The control desired by the User |
|
||||
| `account.createdAt` | String | Date string indicating the moment the User was created |
|
||||
| `account.email` | String | The E-mail address currently tied to the User |
|
||||
| `account.github` | String | The Github username of the User |
|
||||
| `account.img` | String | The URL to the image stored with this User |
|
||||
| `account.imperial` | Boolean| Whether or not the User prefers imperial units |
|
||||
| `account.initial` | String | The E-mail address that the User was created with |
|
||||
| `account.language` | String | The language preferred by the user |
|
||||
| `account.lastLogin` | String | Date string indicating them moment the User last logged in |
|
||||
| `account.mfaEnabled`| Boolean| Whether or not the User has MFA enabled |
|
||||
| `account.newsletter`| Boolean| Whether or not the User is subscribed to the FreeSewing newsletter |
|
||||
| `account.patron` | Number | The level of patronage the user provides to FreeSewing |
|
||||
| `account.role` | String | The role of the User |
|
||||
| `account.status` | Number | The status of the user |
|
||||
| `account.updatedAt` | String | Date string indicating the last time the User was updated |
|
||||
| `account.username` | String | The username of the User |
|
||||
| `account.lusername` | String | A lowercased version of the username of the User |
|
||||
|
||||
## Example request
|
||||
|
||||
```js
|
||||
const udpate = await axios.put(
|
||||
'https://backend.freesewing.org/account/jwt',
|
||||
{
|
||||
bio: "I like imperial now",
|
||||
imperial: true,
|
||||
username: "ImperialLover"
|
||||
},
|
||||
{
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## Example response
|
||||
```200.json
|
||||
{
|
||||
"result": "success",
|
||||
"account": {
|
||||
"id": 14,
|
||||
"bio": "I like imperial now",
|
||||
"consent": 1,
|
||||
"control": 1,
|
||||
"createdAt": "2022-11-19T18:15:22.642Z",
|
||||
"email": "test_54c6856275aaa8a1@freesewing.dev",
|
||||
"github": "",
|
||||
"img": "https://freesewing.org/avatar.svg",
|
||||
"imperial": true,
|
||||
"initial": "test_54c6856275aaa8a1@freesewing.dev",
|
||||
"language": "en",
|
||||
"lastLogin": "2022-11-19T18:15:22.668Z",
|
||||
"mfaEnabled": false,
|
||||
"newsletter": false,
|
||||
"patron": 0,
|
||||
"role": "user",
|
||||
"status": 1,
|
||||
"updatedAt": "2022-11-19T18:15:22.668Z",
|
||||
"username": "ImperialLover",
|
||||
"lusername": "imperiallover"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[duri]: https://en.wikipedia.org/wiki/Data_URI_scheme
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: User login
|
||||
---
|
||||
|
||||
<Fixme>Create docs</Fixme>
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: MFA
|
||||
---
|
||||
|
||||
<Fixme>Create docs</Fixme>
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: Update a User
|
||||
---
|
||||
|
||||
<Fixme>Create docs</Fixme>
|
||||
Loading…
Add table
Add a link
Reference in a new issue