Merge branch '98-add-api-tokens-documentation' into 'main'

To integrate your own services with the INJECT platform,

you must acquire an API token that has to be included in all of your API requests.

### Token management

Creating an API token is as simple as creating a user,

which is done through the user management page.

Each token is directly linked to a special user account with a `BOT` group.

Only **admins** can create these users.

The `BOT` user is special in a number of ways:

- It is not possible to log in as the user

- It is not possible to generate credentials for the user

- It has access to _all_ uploaded definitions and exercises

- It cannot be assigned to an exercise/definition

Simply put, the only way to authenticate as the bot user is through the API token present in the HTTP header.

**The API token is accessible only during the creation process,

it cannot be retrieved again in its raw form at a later point.**

It is possible to rotate the token for a bot user,

which will invalidate the previous token and generate a new one **with the same permissions**.

To delete a token, simply delete the user linked to it.

It is also possible to assign tags to the bot user,

which may help with identification if the platform contains many bot users.

#### Token authentication

To use the token for authentication,

the request **must contain** an `api-token` header set to the value of the token.

All requests with a token will be attributed to the user linked to the token.

This can be used for tracking which token was used for which action,

e.g. if a token was used to upload a definition,

the user linked to the token will be in the `Uploaded by` field.

#### Accessible endpoints

When creating a token,

you must decide which endpoints should be accessible with it.

The platform currently allows these endpoints:

- Create an exercise - `createExercise` GraphQL mutation

- Download a definition - `GET /inject/api/v1/definitions/<definition_id>`

- Upload a definition - `POST /inject/api/v1/definitions`

- Validate a definition - `POST /inject/api/v1/definitions/validate`

- Delete a definition - `deleteDefinition` GraphQL mutation

- Read definitions - `definitions` GraphQL query

- Read exercises - `exercises` GraphQL query

- Start an exercise - `startExercise` GraphQL mutation

- Stop an exercise - `stopExercise` GraphQL mutation

- Delete an exercise - `deleteExercise` GraphQL mutation

- Get trainee progress - `GET /inject/api/v1/progress/<username>/`

If an endpoint is not listed, it **is not accessible** through an API token.

For more details on what these endpoints do or what parameters they take,

refer to the appropriate [REST](openapi.yml) or [GraphQL](graphql-docs.md) page.

More endpoints will probably be added in the future.

transfers and other operations not supported by GraphQL. The [REST documentation](swagger-docs.md)

covers endpoints, request methods, parameters, and response formats, offering comprehensive guidance

for integrating with the IXP.

## Integration

The platform also provides an option to allow your own services to perform various actions.

See the [integration](integration.md) documentation for more details.

      - Overview: tech/api/overview.md

      - Rest API documentation: tech/api/swagger-docs.md

      - GraphQL API documentation: tech/api/graphql-docs.md

      - Integration: tech/api/integration.md

    - Definition documentation: 

      - Overview: tech/architecture/definitions/README.md

      - Upgrade definition: tech/architecture/definitions/upgrade.md