API Authentication

octoja uses JWT-based authentication for API clients and an HTTP session cookie for browser-based flows.

After a successful login or refresh, the response body contains an accessToken and a refreshToken, along with tokenType and expiresIn (the access token's lifetime in seconds). Browser-based sign-ins also receive the session cookie octo_session.

Login

POST /api/auth/login

Request body

Example request

{ "mailAddress": "alex@example.com", "password": "example-password", "TOTP": "123456" }

Successful response

{ "tokenType": "Bearer", "accessToken": "eyJ...", "expiresIn": 3600, "refreshToken": "eyJ..." }

Refresh

POST /api/auth/refresh

Exchange a valid refresh token for a new token pair.

Request body

Example request

{ "refreshToken": "eyJ..." }

Successful response

{ "tokenType": "Bearer", "accessToken": "eyJ...", "expiresIn": 3600, "refreshToken": "eyJ..." }

Logout

POST /api/auth/logout

Logs the current browser session out and clears the octo_session cookie.

Using the access token

Include the access token in the Authorization header on authenticated API requests:

Authorization: Bearer <access_token>Content-Type: application/json

To explore the API interactively, open the OpenAPI (Swagger) interface at https://<your-octoja-instance>/openapi/index.html, click Authorize, and paste your access token. Swagger then sends the Authorization header for you, so you can try authenticated requests without writing any code.

OIDC / SSO login

For browser-based single sign-on, octoja supports OIDC providers such as Microsoft.

Discover available providers

GET /api/auth/oidc/providers

Returns the list of OIDC providers configured for your organization. Use this to determine which provider names are valid before initiating a login.

Initiate a login

1. Call GET /api/auth/oidc/{provider}/authorize?returnUrl=<your-frontend-url>.
2. The endpoint returns a JSON object with the provider login URL.
3. Redirect the user to that URL.
4. After the provider login completes, the browser is sent to /api/auth/oidc/callback.
5. If the signed-in user does not have two-factor authentication enabled, the backend sets the session and redirects the browser back to the original returnUrl. If the user has TOTP enabled, no session is issued yet: the browser is redirected to the frontend /login route with an oidcTotpPending code and the returnUrl, and the session is only issued after the second factor is confirmed.

Which providers are available depends on your organization's configuration. Microsoft is enabled by default, and Google support exists but is disabled by default.

Authentication errors