freesewing/markdown/dev/reference/backend/api/en.md

title
REST API

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) 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:

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.

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:

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