This document explains how to integrate Jodoo as an Identity Provider (IdP) to enable password-free login for your application.

After integration, password-free login is supported in two scenarios:

Jodoo-Initiated Login: The user clicks Enter App in the Jodoo Product Center and is automatically redirected to your system and logged in.
Third-Party-Initiated Login: The user starts from your system and signs in through Jodoo authorization.

Note: Jodoo acts strictly as an Identity Provider (IdP). Its role is to verify the user and return a confirmed identity (such as a Member ID). Your system is entirely responsible for maintaining its own login state — whether through sessions, tokens, or cookies.

1. Authorization Flows

Jodoo supports two authorization flows. The correct one depends on where the user journey begins.

Flow	When to Use	Starting Point	Purpose
Homepage Redirect Flow	When login starts from Jodoo	Jodoo Product Center	Jodoo redirects the user to your application entry point with a temporary code
OAuth Authorization Flow	When login starts from your system	Your platform	Your system redirects the user to Jodoo for authorization

Both flows eventually converge at the same step: your backend exchanges the returned code for the user’s identity.

Flow 1: Homepage Redirect Flow (Jodoo-Initiated)

This flow is used when the user starts from the Jodoo platform.

How it works

The user clicks Enter App in the Jodoo Product Center.
Jodoo redirects the browser to the configured App Homepage.
Jodoo appends a temporary code parameter to the URL.
Your server extracts the code from the request.
Your server calls the Jodoo backend API to exchange the code for the user’s identity.
Your server matches the returned identity to a user in your own system.
Your system creates its own login session and redirects the user to the actual application.

Flow 2: OAuth Authorization Flow (Third-Party-Initiated)

This flow is used when the user starts from your platform and chooses to sign in with Jodoo.

Step 1 Construct the authorization URL

When you click "Log in with Jodoo", redirect their browser to the following URL:

https://app.jodoo.com/open/user/oauth/login?app_id={Suite_ID}&state={STATE}&redirect_uri={REDIRECT_URI}

Parameter	Description	Required
app_id	The Suite ID of your integrated app in Jodoo	Yes
state	A random string generated by your server to prevent CSRF attacks	Yes
redirect_uri	The URL-encoded callback URL that Jodoo redirects to after authorization. It must match a configured trusted domain	Yes

Step 2 Handle the Jodoo callback

After you approve the authorization, Jodoo redirects them back to your redirect_uri with two parameters appended:

Parameter	Description
code	A short-lived, single-use authorization code used to retrieve user identity
state	The exact same value passed in Step 1

Step 3 Verify and exchange

Your server must first verify that the returned state matches the one originally generated.

If the state does not match, reject the request immediately to prevent CSRF attacks.
If the state is valid, use the code to call the Jodoo API and retrieve the user’s identity.
Then match the identity to a local account and complete login in your own system.

How to Get the User Identity API?

Both flows converge at this step:

Once your server has a code, use this API to exchange it for your Jodoo identity.

Note:

This API must only be called from your backend server. Never expose the Suite Secret or make this request from frontend code.

API Reference

This section explains what the API is used for and how to call it.

Purpose

This API retrieves information about the currently logged-in user.

It is used when integrating Jodoo with a third-party application, so the third-party system can use the returned user information to enable single sign-on access.

Request Information

Request URL

https://api.jodoo.com/api/v3/user/oauth/auth_info

Request Method

POST

Request Details

Request Headers

Parameter	Value	Required	Description
Authorization	`Bearer {Suite Secret}`	Yes	Suite Secret is the core credential obtained from the integration app.
Content-Type	`application/json`	Yes	-

Request Body

{
  "code": "xxxxx"
}

Response Details

Successful Response Fields

Field	Type	Description
tenant_id	`string`	Tenant ID, the unique ID of the enterprise in Jodoo. You can view it in Management > Business Info.
username	`string`	Member ID, the unique ID of the member within the current enterprise. You can view it in Management > Members.

Successful Response Example

{
    "tenant_id": "620a31c23e7c5a00081e7acf",
    "username": "jodoo-developer"
}

Full Example Request (cURL)

curl --location 'https://api.jodoo.com/api/v3/user/oauth/auth_info' \
--header 'Authorization: Bearer YOUR_SUITE_SECRET' \
--header 'Content-Type: application/json' \
--data '{
    "code": "USER_CODE"
}'

Parameters in the example

YOUR_SUITE_SECRET: Replace with the Suite Secret obtained from the integration app.
USER_CODE: Replace with the code parameter passed by Jodoo during redirection.

Core Principles

1. Separate identity verification from session management

Jodoo only provides verified user identity information, such as the user ID.

Your system must manage its own authenticated session, including:

Session
Token
Cookie
Any other authentication state

Receiving user identity from Jodoo does not automatically mean the user is logged in to your system. Your application must explicitly create and manage that login state.

2. Store the Suite Secret securely

The Suite Secret is a highly sensitive credential.

It must:

Be stored only on the server side
Be used only in backend requests
Never be exposed in frontend code
Never be accessible through the browser

3. Treat `code` as a one-time credential

The code parameter is a temporary, single-use credential.

After your server receives it, it should immediately exchange it for user identity.

Do not:

Store the code long-term in a database
Attempt to reuse the same code
Process it on the frontend

4. Always verify `state`

In the OAuth Authorization Flow, state is required to prevent CSRF attacks.

Your server should:

Generate the state
Store it securely for verification
Compare it strictly when the callback returns
Reject the request immediately if it does not match

Jodoo App Integration Guide