Auth API

Authentication and identity management including OAuth 2.0 flows, session management, password reset, and multi-factor authentication. Supports multiple grant types for different application scenarios.

1 min read

Available Endpoints

Method	Endpoint	Description
`POST`	`/api/auth/identify`	Identify authentication method
`GET`	`/api/auth/sso/discover`	Discover SSO for domain
`POST`	`/api/auth/sso/complete`	Complete SSO authentication

Endpoints

POST

/api/auth/identify

Identify authentication method

Determine the best authentication method for an email address (SSO, password, magic link).

None (public)

Request

curl -X POST "http://localhost:3030/api/auth/identify" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"email":"[email protected]"}'

const response = await fetch("http://localhost:3030/api/auth/identify", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "email": "[email protected]"
}),
});

const data = await response.json();
console.log(data);

Body Parameters

Name	Type	Description
`email`required	string	Email address to identify authentication method `[email protected]`

Response 200

Authentication method identified

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "method": "password",
  "ssoProvider": "okta",
  "ssoRedirectUrl": "string",
  "hasPasskey": false,
  "allowMagicLink": true
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

GET

/api/auth/sso/discover

Discover SSO for domain

Find organization SSO configuration by email domain.

None (public)

Request

curl -X GET "http://localhost:3030/api/auth/sso/discover" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"

const response = await fetch("http://localhost:3030/api/auth/sso/discover", {
method: "GET",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
});

const data = await response.json();
console.log(data);

Query Parameters

Name	Type	Description
`domain`required	string	Email domain to check for SSO configuration `acme.com`

Response 200

SSO discovery result

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "organizationSlug": "acme-corp",
  "organizationName": "Acme Corporation",
  "ssoProvider": "okta",
  "loginUrl": "https://api.example.com/auth/sso/acme-corp/login"
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

POST

/api/auth/sso/complete

Complete SSO authentication

Exchange an SSO token for an authenticated session.

None (public)

Request

curl -X POST "http://localhost:3030/api/auth/sso/complete" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"handle":"string"}'

const response = await fetch("http://localhost:3030/api/auth/sso/complete", {
method: "POST",
headers: {
  "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  "handle": "string"
}),
});

const data = await response.json();
console.log(data);

Body Parameters

Name	Type	Description
`handle`required	string	Opaque single-use handle issued by /api/auth/sso/callback. Exchanged server-side for the signed completion token; the token itself is never exposed to the browser.

Response 200

SSO authentication completed

{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
  "userId": "507f1f77bcf86cd799439011",
  "email": "[email protected]"
}
}

Error Responses

401— Unauthorized - Invalid or missing authentication

{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}

403— Forbidden - Insufficient permissions

{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}

API Keys API

Organizations API