API Reference

Account Service API

Reference for the Kaleron authentication & account-linking endpoints.

Base URL · https://auth.kaleron.org/

Authentication

/api/auth

Registration, login, and session management. Sessions are carried by a token cookie (HttpOnly, SameSite=Lax, 48-week lifetime).

POST /api/auth/register

Creates a new account and signs the user in immediately.

Body: JSON

Query parameters

Name	Type	Required	Description
`next`	string	optional	URL to redirect to after registration. Defaults to the login page.

Request body

Field	Type	Required	Description
`email`	string	required	Account email address.
`username`	string	required	Unique username.
`password`	string	required	Plaintext password (hashed with Argon2 server-side).

Example request

POST /api/auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "username": "your_handle",
  "password": "••••••••"
}

Responses

302 → next / login 200 MISSING_PARAMETERS 200 ACCOUNT_ALR_EXIST

Note: error cases currently return HTTP 200 with a message field rather than a 4xx status.

GET /api/auth/login

Renders the sign-in / sign-up page.

Returns: HTML

Responses

200 auth.html

POST /api/auth/login

Authenticates a user by email or username and issues a session cookie.

Body: JSON

Query parameters

Name	Type	Required	Description
`next`	string	optional	Redirect target after successful login.

Request body

Field	Type	Required	Description
`input1`	string	required	Email address or username.
`password`	string	required	Account password.

Example request

POST /api/auth/login
Content-Type: application/json

{
  "input1": "[email protected]",
  "password": "••••••••"
}

Responses

302 → next / login 200 MISSING_PARAMETERS 200 INVALID_CREDENTIALS

GET /api/auth/logout

Clears the session cookie and redirects to the login page.

Responses

302 → /api/auth/login

Account Linking

/api/link

OAuth-style flow that lets a third-party application request access to a Kaleron account. The user is asked to authorize a set of permissions, then redirected back to the calling application with a short-lived exchange code. Data-reading endpoints require that the link's creator_token was granted the matching permission.

GET /api/link/getUserEmail

Returns the email address of the account bound to a link token, provided the creator token holds the read_email permission.

Returns: JSON

Query parameters

Name	Type	Required	Description
`token`	string	required	Link token identifying the authorized account.

Example request

GET /api/link/getUserEmail?token=a1b2c3d4e5

Responses

200 { success, email } 400 token is required 403 MISSING_PERMISSION 404 token or link not found

GET /api/link/getUsername

Returns the username of the account bound to a link token, provided the creator token holds the read_username permission.

Returns: JSON

Query parameters

Name	Type	Required	Description
`token`	string	required	Link token identifying the authorized account.

Example request

GET /api/link/getUsername?token=a1b2c3d4e5

Responses

200 { success, username } 400 token is required 403 MISSING_PERMISSION 404 token or link not found

GET /api/link/getConnections

Returns the connection identifier of the linked account, provided the creator token holds the read_username permission.

Returns: JSON

Query parameters

Name	Type	Required	Description
`token`	string	required	Link token identifying the authorized account.

Example request

GET /api/link/getConnections?token=a1b2c3d4e5

Responses

200 { success, connections } 400 token is required 403 MISSING_PERMISSION 404 token or link not found

GET /api/link/auth-link

Renders the authorization consent page for a given link request.

Returns: HTML

Query parameters

Name	Type	Required	Description
`creator_token`	string	required	Identifier of the link token created by the third-party application.

Responses

200 LinkRequest.html 302 → login (if not signed in) 302 → accept_redirect_uri?code=… (if already linked) 400 creator token is required 404 link infos not found

POST /api/link/auth-link/accept

Confirms the authorization: records the link, generates an exchange code (valid 60 s in Redis) and redirects to the application's accept_redirect_uri.

Body: form-data

Form parameters

Field	Type	Required	Description
`creator_token`	string	required	Identifier of the link token to authorize.

Responses

302 → accept_redirect_uri?code=… 302 → login (if not signed in) 400 creator token is required 404 link infos not found

POST /api/link/auth-link/refuse

Declines the authorization request and redirects the user back to the application's refused_redirect_uri without issuing any code.

Body: form-data

Form parameters

Field	Type	Required	Description
`creator_token`	string	required	Identifier of the link token to decline.

Responses

302 → refused_redirect_uri 302 → login (if not signed in) 400 creator token is required 404 link infos not found

GET /api/link/getTokenViaCode

Exchanges a short-lived code (received on the redirect) for the persistent link token used to read account data.

Returns: JSON

Query parameters

Name	Type	Required	Description
`code`	string	required	Exchange code returned to accept_redirect_uri (valid 60 s, single use).

Example request

GET /api/link/getTokenViaCode?code=a1b2c3d4e5

Responses

200 { success, token } 200 Code is required 200 Invalid or expired code

Note: the missing-code and invalid-code cases currently return HTTP 200 with a message field rather than a 4xx status. The returned token can then be used with the getUserEmail, getUsername and getConnections endpoints.

Service

/api/accounts

Convenience endpoints exposed by the website backend that proxy the Kaleron account service on behalf of the currently signed-in user.

GET /api/accounts/link-approval

Fetches the accounts linked to the current session by forwarding the token cookie to the upstream account service.

Returns: JSON

Responses

200 accounts (JSON) 401 UNAUTHORIZED 500 upstream error