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

title
API Keys

Documentation for the REST API endpoints to create, read, or remove API keys.

The FreeSewing backend REST API supports authentication both with JSON Web Tokens (JWT) as with API keys (KEY). This describes the endpoints that deal with creating, reading, and removing API keys. For authentication details, refer to [the section on authenticating to the API](/reference/backend/api#authentication).

Create a new API key

Create a new API key. The API key will belong to the user who is authenticated when making the call. Supported for both JWT and KEY authentication.

The response to this API call is the only time the secret will be revealed.

Endpoints

Method	Path	Description	Auth
	/apikey/jwt	Create a new API key	jwt
	/apikey/key	Create a new API key	key

Parameters

| Where | Variable | Type | Description | | ----- | ------------- | -------- | ----------- | | _body_ | `name` | `string` | Create a new API key. Endpoint for JWT authentication | | _body_ | `level` | `number` | A privilege level from 0 to 8. | | _body_ | `expiresIn` | `number` | body | The number of seconds until this key expires. | Returns HTTP status code on success, if the request is malformed, and on server error.

Value	Type	Description
result	string	created on success, and error on error
apikey.key	string	The API key
apikey.secret	string	The API secret
apikey.level	number	The privilege level of the API key
apikey.expiresAt	string	A string representation of the moment the API key expires
apikey.name	string	The name of the API key
apikey.userId	number	The ID of the user who created the API key

### Example ```js const apiKey = axios.post( 'https://backend.freesewing.org/apikey/jwt', { name: 'My first API key', level: 2, // Read only expiresIn: 3600, // One hour }, { headers: { Authorization: `Bearer ${token}` } } ) ```

{
  result: 'success',
  apikey: {
    key: '7ea12968-7758-40b6-8c73-75cc99be762b',
    secret: '503d7adbdb3ec18ab27adfcd895d8b47a8d6bc8307d548500fbf9c05a5a8820e',
    level: 3,
    expiresAt: '2022-11-06T15:57:30.190Z',
    name: 'My first API key',
    userId: 61
  }
}

Read an API key

Reads an existing API key. Note that the API secret can only be retrieved at the moment the API key is created.

You need the `admin` role to read API keys of other users ### Endpoints

Method	Path	Description	Auth
	/apikey/:id/jwt	Reads an API key	jwt
	/apikey/:id/key	Reads an API key	key

Parameters

| Where | Variable | Type | Description | | ----- | ----------- | -------- | ----------- | | _url_ | `:id` | `string` | The `key` field of the API key | Returns HTTP status code on success, if the request is malformed, if the key is not found, and on server error.

Value	Type	Description
result	string	success on success, and error on error
apikey.key	string	The API key
apikey.level	number	The privilege level of the API key
apikey.expiresAt	string	A string representation of the moment the API key expires
apikey.name	string	The name of the API key
apikey.userId	number	The ID of the user who created the API key

### Example ```js const keyInfo = axios.get( 'https://backend.freesewing.org/apikey/7ea12968-7758-40b6-8c73-75cc99be762b/jwt', { headers: { Authorization: `Bearer ${token}` } } ) ```

{
  result: 'success',
  apikey: {
    key: '7ea12968-7758-40b6-8c73-75cc99be762b',
    level: 3,
    expiresAt: '2022-11-06T15:57:30.190Z',
    name: 'My first API key',
    userId: 61
  }
}

Read the current API key

Reads the API key with which the current request was authenticated.

Endpoints

Method	Path	Description	Auth
	/whoami/key	Reads the current API key	key

Parameters

This endpoint takes no parameters Returns status code `200` on success, `400` on if the request is malformed, `404` if the key is not found, and `500` on server error.

Value	Type	Description
result	string	success on success, and error on error
apikey.key	string	The API key
apikey.level	number	The privilege level of the API key
apikey.expiresAt	string	A string representation of the moment the API key expires
apikey.name	string	The name of the API key
apikey.userId	number	The ID of the user who created the API key

### Example ```js const keyInfo = axios.get( 'https://backend.freesewing.org/whoami/key', { auth: { username: apikey.key, password: apikey.secret, } } ) ```

{
  result: 'success',
  apikey: {
    key: '7ea12968-7758-40b6-8c73-75cc99be762b',
    level: 3,
    expiresAt: '2022-11-06T15:57:30.190Z',
    name: 'My first API key',
    userId: 61
  }
}

Remove an API key

Removes an existing API key.

You need the `admin` role to remove API keys of other users

Endpoints

Method	Path	Description	Auth
	/apikey/:id/jwt	Removes an API key	jwt
	/apikey/:id/key	Removes an API key	key

Parameters

| Where | Variable | Type | Description | | ----- | ----------- | -------- | ----------- | | _url_ | `:id` | `string` | The `key` field of the API key | Returns HTTP status code on success, if the request is malformed, if the key is not found, and on server error. ### Example ```js const keyInfo = axios.get( 'https://backend.freesewing.org/apikey/7ea12968-7758-40b6-8c73-75cc99be762b/jwt', { headers: { Authorization: `Bearer ${token}` } } ) ``` Status code (no content) does not come with a body

Notes

The following is good to keep in mind when working with API keys:

This is not the authentication documentation

The FreeSewing backend REST API supports authentication both with JSON Web Tokens (JWT) as with API keys (KEY).

This describes the endpoints that deal with creating, reading, and removing API keys. For authentication details, refer to the section on authenticating to the API.

API keys are immutable

Once created, API keys cannot be updated. You should remove them and re-create a new one if you want to make change.

API keys have an expiry

API keys have an expiry date. The maximum validity for an API key is 1 year.

API keys have a permission level

API keys have a permission level. You can never create an API key with a higher permission level than your own permission level.

Circumstances that will trigger your API keys to be revoked

As a precaution, all your API keys will be revoked when:

• Your role is downgraded to a role with fewer privileges
• Your account is (b)locked
• You revoke your consent for FreeSewing to process your data

This is not an exhaustive list. For example, if we find your use of our API to be excessive, we might also revoke your API keys to shield us from the financial impact of your use of our API.