Token-authenticated API by AlexandreDoneux · Pull Request #1121 · INGInious/INGInious

AlexandreDoneux · 2026-07-09T15:12:19Z

This PR adds two endpoints to retrieve submissions using a token and a way for a user to generate it.

The token can be generated from the user preferences, in the page "API token". It is implemented using a JWT, allowing an automatic expiration.

The endpoints :

/api/v0/token/courses/<courseid>/submissions
- Returns the submissions of a course, and the data related to them.
/api/v0/token/courses/<courseid>/<taskid>/submissions
- Returns the submissions of a particular task

Both are POST endpoint due to the use of parameters passed through a JSON body. Passing them as arguments or parameters through the url could become cumbersome.
That body can contain :

select: "all" (default), "best", "last" : select all submissions, the best submission per student, or the last submission per student
username: a list of usernames to filter the submissions. If none is provided (or it is empty), the submissions for all users are returned
format: "json" (default), "csv" : format of the response.

Yet to bee implemented :

Removing test endpoint
Add csv formatting for the endpoint's response
Add the JWT lifetime and secret in the webapp configuration
Work on api token page in the UI, multiple tokens with invalidation, token only visible once at generation
Store hash of token
store token secret and lifetime in config
Change endpoint names
Complete doc

codacy-production · 2026-07-09T15:16:13Z

Not up to standards ⛔

🔴 Issues 2 medium

Alerts:
⚠ 2 issues (≤ 0 issues of at least minor severity)

Results:
2 new issues

Category Results

Complexity 2 medium

View in Codacy

🟢 Metrics 0 duplication

Metric Results

Duplication 0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

anthonygego

I did a first pass of things that shoud be addressed before going further.

AlexandreDoneux · 2026-07-27T14:42:56Z

I have addressed your current remarks. I have on my end other questions I would like to submit to you :

endpoint names : I have for the moment used /api/v0/token in the endpoints I have added. However since we don't use the flask session anymore all endpoints use th token authentication and this distinction is not needed anymore. I will change that. But do you want to change the version of the api ?
POST input : I used the JSON input format for the endpoints I added. Should we stick to the form format ? It is necessary for the endpoint to add a submission for a file problem as JSON input does not support files. I therefore added both formats for that endpoint. But it might be better to stick to one format.
I kept a HS256 symmetric algorithm for JWT as it is simple and the INGInious "backend" is the only one encoding and decoding the JWTs. Is i enough or should we use an asymmetric algorithm ?

anthonygego · 2026-07-27T15:06:00Z

endpoint names : I have for the moment used /api/v0/token in the endpoints I have added. However since we don't use the flask session anymore all endpoints use th token authentication and this distinction is not needed anymore. I will change that. But do you want to change the version of the api ?

Yes, I think we can, even if the interface doesn't change. That will invalide any old usage of the API. No need to preserve any retrocompatibility, the thing was broken for years.

POST input : I used the JSON input format for the endpoints I added. Should we stick to the form format ?

No JSON's probably good.

It is necessary for the endpoint to add a submission for a file problem as JSON input does not support files. I therefore added both formats for that endpoint. But it might be better to stick to one format.

This is not something bad I guess. This practice can be found in other software. For instance, in Grist, the endpoint for creating a new document supports the two body schema, json and multipart : https://support.getgrist.com/api/#tag/docs/operation/importDoc

The main requirement remains that the API is usable through standard librairies and methods.

I kept a HS256 symmetric algorithm for JWT as it is simple and the INGInious "backend" is the only one encoding and decoding the JWTs. Is i enough or should we use an asymmetric algorithm ?

I guess that's enough, indeed, as long as the symmetric algorithm is robust enough for a few years.

anthonygego

In summary, there are 3 things that need attention here:

The way the user is propagated between parent and children API classes.
Tokens and hashes sent in post forms.
The way submission input are served.

…when calling endpoint

…xpiration with timezone

…ourse

…into account differrent tasks previously did not differentiate tasks. The API would send the best result for each course, but not all tasks.

… info

… instead of session

…(without session) + fixes + use json input for post

Transform into class methods + determine method directly inside verify_hash()

… if expired

nrybowski

All in all, this PR requires some heavy lifting.

nrybowski · 2026-08-28T11:38:58Z

-    flask_app.add_url_rule('/api/v0/auth_methods',
-                           view_func=APIAuthMethods.as_view('apiauthmethods'))
-    flask_app.add_url_rule('/api/v0/authentication',
-                           view_func=APIAuthentication.as_view('apiauthentication'))
-    flask_app.add_url_rule('/api/v0/courses', view_func=APICourses.as_view('apicourses.alias'),
+    flask_app.add_url_rule('/api/v1/courses', view_func=APICourses.as_view('apicourses.alias'),


Bumping the API version is a breaking change that is not even documented in the PR description. Is the bump mandatory? If yes, document it extensively and maybe add dummy endpoints for the old version. That is the kind of silent breaking change we really do not want in production.

In this PR we change from authentication using the flask session to a token. Using the endpoints as before will inevitably fail. Bumping the version feels to me like a good way to indicate such a big change.

Although I will grant you this is missing some documentation. Plus, when calling an non-existent url, INGInious send back an HTML page. I will implement specific messages for "/api" and "/api/v0" to indicate an endpoint is not available or is obsolete.

Should I keep legacy endpoints rather than returning an error ?

nrybowski · 2026-08-28T16:40:57Z

endpoint names : I have for the moment used /api/v0/token in the endpoints I have added. However since we don't use the flask session anymore all endpoints use th token authentication and this distinction is not needed anymore. I will change that. But do you want to change the version of the api ?

Yes, I think we can, even if the interface doesn't change. That will invalide any old usage of the API. No need to preserve any retrocompatibility, the thing was broken for years.

I'm uncomfortable with such a breaking change, we should deploy dummy endpoints documenting the API changes for any scripts out there in the wild that may still use the old (and maybe broken) API. Maybe some 301 with a payload rather than just plain 404 out of nowhere. Such endpoints should only be available for a single release.

nrybowski · 2026-08-28T16:54:00Z

Regarding to https://github.com/INGInious/INGInious/pull/1121/changes#r3880972260, we could generate a token per course upon admin user request, the authorized course id would be embedded within the JWT. Hence, we should not even load to course to ensure that the user is authorized to call the submission API for the specified course.
This could be implemented in the same manner as the webdav access token on the course administration page.
@anthonygego your thoughts?

anthonygego · 2026-08-31T07:09:52Z

Regarding to https://github.com/INGInious/INGInious/pull/1121/changes#r3880972260, we could generate a token per course upon admin user request, the authorized course id would be embedded within the JWT. Hence, we should not even load to course to ensure that the user is authorized to call the submission API for the specified course. This could be implemented in the same manner as the webdav access token on the course administration page. @anthonygego your thoughts?

Yes that was planned for #1041 and #1042 but the work was not finished by the end of the internship. I was in favor of both user (mainly for submission) and course (mainly for stats) tokens. This can in practice just be implemented as scopes, I don't know. The main requirements is that students should be able to generate tokens too without being manageable by course admins.

But I really think that one feature must be implemented at a time in order to move on.

…her endpoints

…y in memory

…frontend list

AlexandreDoneux · 2026-09-01T12:53:01Z

I chose to hardcode the algorithm used for JWT. Allowing the choice for it could become messy due to different algorithms using different values (secrets, public keys, private keys). We would need to keep track of all the algorithms as well as all the different secrets and keys used to allow old tokens.

On top of that, changing from a symmetric to an asymmetric algorithm without changing the secret could lead to an algorithm-confusion attack.

AlexandreDoneux · 2026-09-09T18:54:35Z

Closing this PR. We will implement the submissions API and the generation and use of tokens through smaller PRs. Starting with #1170.

anthonygego requested changes Jul 14, 2026

View reviewed changes

AlexandreDoneux force-pushed the submissions_api branch 2 times, most recently from fae1614 to be20b09 Compare July 27, 2026 14:34

AlexandreDoneux force-pushed the submissions_api branch from ecf3c1e to 83d28ba Compare August 6, 2026 08:58

anthonygego added the Priority: High label Aug 6, 2026

AlexandreDoneux marked this pull request as ready for review August 6, 2026 12:02

anthonygego requested changes Aug 6, 2026

View reviewed changes

anthonygego changed the title ~~Submissions api~~ Token-authenticated API Aug 6, 2026

nrybowski self-requested a review August 10, 2026 12:28

nrybowski force-pushed the main branch 7 times, most recently from a26321f to 9835953 Compare August 11, 2026 12:48

AlexandreDoneux force-pushed the submissions_api branch from 83d28ba to e3c10e4 Compare August 14, 2026 15:14

AlexandreDoneux added 10 commits August 25, 2026 09:34

[frontend/api] Basic access endpoints with fixed token

1666926

[frontend/api] Adding fixed token to User document + verifying token …

ec85e74

…when calling endpoint

[frontend] Adding api token page in user preferences

a0c3656

[pages/preferences] Adding JWT with expiration (display and generation)

22bba0f

[pages/api] Adding complete JWT check for API calls + display token e…

2a6dd64

…xpiration with timezone

[api/submissions] basic token endpoint sending all submissions of a c…

bf96481

…ourse

[api/submissions] Implement best/last for submissions

dae68de

[api/submissions] Refactor submissions api for a course + fix : take …

405054c

…into account differrent tasks previously did not differentiate tasks. The API would send the best result for each course, but not all tasks.

[api/submissions] Add correct format for "submitted_on" in submission…

74c19d7

… info

[api/submissions] Adding complete input info for submissions

da0d17f

AlexandreDoneux added 14 commits August 25, 2026 09:34

[api/submissions] Adapt previous endpoints to use username from token…

baeb030

… instead of session

[api/submissions] Refactor old submissions endpoint to use the token …

a3ae3b8

…(without session) + fixes + use json input for post

Move API JWT params to app configuration

5217a1b

[frontend/user_manager] Adapting hashing verification methods

d8f60c8

Transform into class methods + determine method directly inside verify_hash()

[api] Hashing API tokens

560c642

[api] Clearer errors for API token + colored date for API token in UI…

6d9fcf0

… if expired

[api] removing JWT algorithm from configuration

b075c77

[api/submissions] Complete documentation

d6ac789

[api] Update API version to v1

bf1404a

[api] Remove session authetification endpoints

8556807

[api] Adapt courses and tasks endpoints to new token authentification

2ebb12e

[api] Multiple fixes/reverts

39149bf

[api/submissions] Remove CSV format for response

2074242

[api] Avoid user concurency by using flask global

3d98845

nrybowski requested changes Aug 28, 2026

View reviewed changes

AlexandreDoneux added 4 commits August 31, 2026 12:19

[api/submissions] submission download endpoint + remove input from ot…

2171012

…her endpoints

[api/submissions] Stream submission download to avoid loading it full…

2df48e0

…y in memory

[models/user] Use MapField for apitokens + do not send token hash to …

6c8abb5

…frontend list

[api] Limit generating new token to one POST

f1ec41f

AlexandreDoneux force-pushed the submissions_api branch from e3c10e4 to f1ec41f Compare August 31, 2026 10:21

AlexandreDoneux added 3 commits August 31, 2026 14:52

[frontend/apitoken] Allow users to choose API token expiration

62ad414

[API] Remove JWT algorithm choice for API tokens

4a69892

[api/submissions] Adding streaming for large list of submissions

d366f32

AlexandreDoneux mentioned this pull request Sep 9, 2026

Generation of api tokens and the use of said tokens for the api endpoints #1170

Open

AlexandreDoneux closed this Sep 14, 2026

Uh oh!

Conversation

AlexandreDoneux commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codacy-production Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Not up to standards ⛔

Uh oh!

anthonygego left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlexandreDoneux commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anthonygego commented Jul 27, 2026

Uh oh!

anthonygego left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nrybowski left a comment

Choose a reason for hiding this comment

Uh oh!

nrybowski Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

AlexandreDoneux Aug 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nrybowski commented Aug 28, 2026

Uh oh!

nrybowski commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anthonygego commented Aug 31, 2026

Uh oh!

AlexandreDoneux commented Sep 1, 2026

Uh oh!

AlexandreDoneux commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlexandreDoneux commented Jul 9, 2026 •

edited

Loading

codacy-production Bot commented Jul 9, 2026 •

edited

Loading

AlexandreDoneux commented Jul 27, 2026 •

edited

Loading

nrybowski commented Aug 28, 2026 •

edited

Loading