Apps and clients using features that require authentication must be registered.
Request Authorization with your App
Send the AuthorizationRequest
Receive the AuthorizationGranted
Introduce your app by sending a mail to mail@mensa-kl.de.
Attach a configuration file describing your client(s).
{
"contact_mail": "your-email@example.com",
"clients": [
{
"app_label": "Example App",
"cors_url": "https://example.com",
"auth_url": "https://example.com/my-auth-endpoint"
},
{
"app_label": "Internal Example Test App",
"cors_url": "https://dev.example.com",
"auth_url": "https://dev.example.com/my-auth-endpoint"
}
]
}
string contact_mail:
Used to inform you about API updates or to discuss issues with your apps.
string app_label:
Displayed to the user during the authorization request for your app.
Die Anwendung Example App möchte auf dein mensa-kl.de-Konto zugreifen.
string auth_url (Optional):
The URL that will be redirected to when the user authorizes your app.
string cors_url (Optional):
When CORS is required,
this URL will be added to the allow-list of mensa-kl.de.
⚠️ Do not embed secrets in these details, as all app information can be observed by users tracing the login workflow.
Redirect or open https://www.mensa-kl.de/api/v1/authorize-client.
Provide the query parameters specified as AuthorizationRequest.
The user decides whether your application will be authorized.
If the user accepts the authorization request,
a redirect with AuthorizationGranted payload is sent to your configured auth_url.
Verify the payload before trusting it.
AuthorizationRequesthttps://www.mensa-kl.de/api/v1/authorize-client?client_uuid=${CLIENT_UUID}&csrf_token=${CSRF_TOKEN}
string client_uuid:
The UUID of your app.
This UUID is assigned when you register your app.
string csrf_token:
A run-time generated token to protect against cross-site request forgery requests aimed at your app.
Store it temporarily (e.g., in the session) to verify incoming login credentials.
Do not share this token between users or with third parties.
When mensa-kl.de grants you access,
the secret will be included in the grant.
If the secret is missing or has an unexpected value,
do not attempt to use the provided credentials as they are invalid
(and probably forged by a third-party).
AuthorizationGrantedThe following details are sent to your app's {auth_url}
when the user accepts to share credentials with your app.
https://example.com/my-auth-endpoint?csrf_token=${CSRF_TOKEN}&auth_token=${AUTH_TOKEN}
string csrf_token:
The csrf_token that your app specified when sending the AuthorizationRequest.
Verify that the value is identical to the one your app provided with the request.
If the value is different, ignore the data provided by the AuthorizationGranted
as it is not trustworthy.
string auth_token:
The secret your application uses to make API requests on behalf of the user who granted authorization.
Store the token in the user's client.
Avoid storing it on your server unless absolutely necessary.
Always set the Authorization header to execute API requests on behalf of the user who granted authorization.
Authorization: Bearer {auth_token}
string auth_token:
The token provided by AuthorizationGranted.
Either the user has no permission to call the API endpoint or the token is no longer authorized. Users can terminate sessions. Your app will not be notified when a session gets terminated.