diff --git a/markdown/dev/reference/backend/api/en.md b/markdown/dev/reference/backend/api/en.md index 0139b7cd42b..cf3b96ef608 100644 --- a/markdown/dev/reference/backend/api/en.md +++ b/markdown/dev/reference/backend/api/en.md @@ -8,109 +8,5 @@ This is the reference documentation for the FreeSewing backend REST API. This documentation is under construction as we are re-working this API for v3. -## Purpose of this API - -This API is how one can interact with the FreeSewing backend data. -That means the data for our users, including all people they have added to -their profile, as well as all of the patterns they have saved to our profile. - -This API also manages subscriptions to our newsletter, and a number of other -automation tasks such as creating issues on Github. - -## Authentication - -Apart from a handlful of API endpoints that are accessible without -authentication (typically the ones dealing with the signup flow or password -recovery), this API requires authentication. - -Two different types of authentication are supports: - -- **JSON Web Tokens** (jwt): This is typically used to authenticate humans in a - browser session. -- **API Keys** (key): This is typically used to interact with the API in an - automated way. Like in a script, a CI/CD context, a serverless runner, and so - on. - -For each endpoint, the API has a variant depending on what authentication you -want to use: - -- `/some/route/jwt` : Authenticate with JWT -- `/some/route/key` : Authenticate with an API key and secret - -### JWT authentication - -The use of JSON Web Tokens ([jwt](https://jwt.io)) is typically used in a -browser context where we want to establish a *session*. - -To get a token, you must first authenticate at the `/login` endpoint with -username and password. You will receive a JSON Web Token (jwt) as part of the -response. - -In subsequent API calls, you must then include this token in the -`Authorization` header prefixed by `Bearer`. Like his: - -```js -const account = await axios.get( - `https://backend.freesewing.org/account/jwt`, - { - headers: { - Authorization: `Bearer ${token}` - } - } -) -``` - -### API key authentication - -The combination of API key & secret serves as a username & password for [HTTP -basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). - - -In basic authentication, the password is sent -unencrypted. To guard against this, this API should only be served over a -connectin encrypted with TLS. (a url starting with `https://`). - - -Sending a username and password with a request like this is supported -pretty much everywhere. In addition, there is no need to establish a session -first, so this make the entire transation stateless. - -Below is an example using curl: - -```sh -curl -u api-key-here:api-secret-here \ - https://backend.freesewing.org/account/key -``` - -## Privilege levels for user roles and API keys - -The privilege level is an intiger from `0` to `8`. The higher the number, the higher the priviledge. - -User accounts have a `role` that determines their privilege level. -The available roles (with their privilege levels) are: - -- **user**: `4` -- **bughunter**: `5` -- **support**: `6` -- **admin**: `8` - -These roles are used when using JWT authentication, as that's typically used by humans. -When using API keys, the privilege level can be set on the API key itself in a more granular way. - -The table below lists the priviledge of all levels as well as their corresponding `role`: - -| Level | Abilities | `user` | `bughunter` | `support` | `admin` | -| --: | -- | :--: | :--: | :--: | :--: | -| `0` | authenticate | ✅ | ✅ | ✅ | ✅ | -| `1` | **read** measurements and patterns | ✅ | ✅ | ✅ | ✅ | -| `2` | **read all** account data | ✅ | ✅ | ✅ | ✅ | -| `3` | **write** measurements or patterns | ✅ | ✅ | ✅ | ✅ | -| `4` | **write all** account data | ✅ | ✅ | ✅ | ✅ | -| `5` | **read** measurements or patterns of **other users** | ❌ | ✅ | ✅ | ✅ | -| `6` | **read all** account data of **other users** | ❌ | ❌ | ✅ | ✅ | -| `7` | **write** account data of **other users** through **specific support methods** | ❌ | ❌ | ✅ | ✅ | -| `8` | impersonate other users, **full write access** | ❌ | ❌ | ❌ | ✅ | - -## API Routes - +