Skip to content

Integration

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 or GraphQL page. More endpoints will probably be added in the future.