API Authentication

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

API access is included in the agent price, with no separate charge.

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). Both are opaque strings issued by octoja — store them exactly as you receive them and send them back unchanged. Every successful sign-in, including an API login, also sets the session cookie octo_session, which the octoja web interface uses.

Login

POST /api/auth/login

Request body

Example request

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

Successful response

{ "tokenType": "Bearer", "accessToken": "<access_token>", "expiresIn": 3600, "refreshToken": "<refresh_token>" }

Refresh

POST /api/auth/refresh

Exchange a valid refresh token for a new token pair.

By default, an access token lasts one hour and a refresh token lasts 14 days from issuance. Use expiresIn from the response for the access token's lifetime.

A successful refresh issues a new token pair with fresh lifetimes. Store both new tokens and use them for subsequent requests. If the refresh token has expired, complete the login flow again.

Request body

Example request

{ "refreshToken": "<refresh_token>" }

Successful response

{ "tokenType": "Bearer", "accessToken": "<access_token>", "expiresIn": 3600, "refreshToken": "<refresh_token>" }

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

octoja supports single sign-on through OIDC providers such as Microsoft, both from the browser and from a native app.

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 browser 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.

octoja support sets up which SSO providers are available for your octoja instance. Members of an administrator group can turn already-configured providers off or back on under Settings → Authentication in the SSO providers section. If a provider you want to use, such as Google, is missing there, contact octoja support and provide your octoja instance URL.

Native app login

A native app runs the same flow with PKCE, so the one-time result is handed to the app itself rather than to the system browser.

1. Call GET /api/auth/oidc/{provider}/authorize?returnUrl=<your-callback-uri>&codeChallenge=<pkce_code_challenge>. Use exactly the callback URI enabled by our support team as returnUrl.
2. Open the returned URL in the system browser so the user can sign in with the provider.
3. The callback sends the browser to your callback URI with a one-time handoff code in the query string.
4. Redeem that code from the app with POST /api/auth/oidc/handoff, passing the PKCE verifier that matches the challenge from step 1: { "handoff": "<handoff_code>", "codeVerifier": "<pkce_code_verifier>" }. The response carries the same token pair as a password login.
5. If the user has two-factor authentication enabled, the handoff call answers 403 Forbidden and keeps the code valid — repeat the same request with the user's one-time code added.

Authentication errors