Auth

AuthRpc provides the RPC surface for authentication, signup, verification, password recovery, OAuth login URL generation, session inspection, logout, and client configuration retrieval. The methods documented below are the public RPC methods that are not marked as internal-only in the source file.

Endpoints

POST /api/rpc (Method: AuthRpc.preSignupValidate)

This method performs pre-signup validation before account creation. It checks blacklist rules, email and username uniqueness, and invite code validity when invite-based signup is enabled.

• Description: Performs pre-signup validation for uniqueness, blacklists, and invite codes without creating a user.

• Request Body:

  {
    "method": "AuthRpc.preSignupValidate",
    "params": {
      "email": "[email protected]",
      "username": "newuser",
      "inviteCode": "ABC123"
    }
  }

• Parameters:

  Name	Type	Required	Description
  email	String	Yes	Email address to validate. The schema is inherited from UserSignupSchema; the exact constraints were not inspected here.
  username	String	Depends on UserSignupSchema	Username to validate. The exact constraints were not inspected here.
  inviteCode	String	No	Optional invite code. When invite-code signup is enabled, the method requires it.

• Response:

  {
    "success": true,
    "message": "Validation successful."
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "AuthRpc.preSignupValidate",
      "params": {
        "email": "[email protected]",
        "username": "newuser"
      }
    }'

POST /api/rpc (Method: AuthRpc.requestVerificationCode)

This method requests a one-time verification code for an email address or phone number. It forwards the request to the verification subsystem and returns that service’s response.

• Description: Requests a one-time verification code to be sent to an email or phone number.

• Request Body:

  {
    "method": "AuthRpc.requestVerificationCode",
    "params": {
      "channelType": "email",
      "identifier": "[email protected]",
      "contactInfo": {
        "firstName": "Ada",
        "lastName": "Lovelace",
        "contactId": "contact-123"
      }
    }
  }

• Parameters:

  Name	Type	Required	Description
  channelType	String	Yes	Verification channel. Must be one of email, sms, or whatsapp.
  identifier	String	Yes	Target email address or phone number, depending on the selected channel.
  contactInfo	Object	No	Optional contact context forwarded with the request.
  contactInfo.firstName	String	No	Optional first name.
  contactInfo.lastName	String	No	Optional last name.
  contactInfo.contactId	String	No	Optional existing contact ID. The schema marks this field as nullable.

• Response:

  {
    "success": true,
    "data": {}
  }

  The exact response shape is determined by VerificationService.requestOtp(...) and was not inspected here.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "AuthRpc.requestVerificationCode",
      "params": {
        "channelType": "email",
        "identifier": "[email protected]"
      }
    }'

POST /api/rpc (Method: AuthRpc.verifyCode)

This method verifies a one-time password against an OTP request ID. It can optionally finalize the request.

• Description: Verifies an OTP code against a request ID without creating a user.

• Request Body:

  {
    "method": "AuthRpc.verifyCode",
    "params": {
      "otpRequestId": "otp-request-123",
      "code": "123456",
      "finalize": false
    }
  }

• Parameters:

  Name	Type	Required	Description
  otpRequestId	String	Yes	OTP request identifier. Must not be empty.
  code	String	Yes	OTP code to verify.
  finalize	Boolean	No	When provided, defaults to false. If true, the OTP request is finalized after verification.

• Response:

  {
    "success": true,
    "data": {}
  }

  The exact response shape is determined by VerificationService.verifyOtp(...) and was not inspected here.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "AuthRpc.verifyCode",
      "params": {
        "otpRequestId": "otp-request-123",
        "code": "123456"
      }
    }'

POST /api/rpc (Method: AuthRpc.signup)

This method creates a new user account. When configured, it can also enforce pre-signup verification and invite-code validation before delegating account creation to the user service.

• Description: Signs up a new user and creates their initial subscription/tenant.

• Request Body:

  {
    "method": "AuthRpc.signup",
    "params": {
      "email": "[email protected]",
      "username": "newuser",
      "inviteCode": "ABC123",
      "verifications": {
        "email": {
          "otpRequestId": "otp-request-123",
          "code": "123456"
        }
      }
    }
  }

• Parameters:

  Name	Type	Required	Description
  email	String	Yes	Signup email. The schema is inherited from UserSignupSchema; the exact constraints were not inspected here.
  username	String	Depends on UserSignupSchema	Username to create. The exact constraints were not inspected here.
  inviteCode	String	No	Optional invite code. Required only when invite-code signup is enabled.
  verifications	Object	No	Optional verification payload used when pre-signup verification mode is enabled.
  verifications.email	Object	No	Email verification data. Required when email pre-verification is enabled.
  verifications.email.otpRequestId	String	Yes when present	OTP request ID for the email verification step.
  verifications.email.code	String	Yes when present	OTP code for the email verification step.
  verifications.phone	Object	No	Phone verification data. Required when phone pre-verification is enabled.
  verifications.phone.otpRequestId	String	Yes when present	OTP request ID for the phone verification step.
  verifications.phone.code	String	Yes when present	OTP code for the phone verification step.

• Response:

  {
    "success": true,
    "data": {}
  }

  The method returns the result of UserService.signupAndCreateSubscription(...). The exact response shape was not inspected here.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "AuthRpc.signup",
      "params": {
        "email": "[email protected]",
        "username": "newuser"
      }
    }'

POST /api/rpc (Method: AuthRpc.getOAuthLoginUrl)

This method returns a server-side OAuth login path for the requested provider.

• Description: Gets the server-side URL to initiate an OAuth login flow.

• Request Body:

  {
    "method": "AuthRpc.getOAuthLoginUrl",
    "params": {
      "provider": "google"
    }
  }

• Parameters:

  Name	Type	Required	Description
  provider	String	Yes	OAuth provider name, such as google.

• Response:

  {
    "success": true,
    "data": {
      "url": "/auth/google"
    }
  }

  The returned URL is a relative path in the form /auth/{provider}.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "AuthRpc.getOAuthLoginUrl",
      "params": {
        "provider": "google"
      }
    }'

POST /api/rpc (Method: AuthRpc.createExternalOAuthLoginSession)

This method starts an OAuth login session intended for external browser flows, such as desktop containers. It uses the current request base URL when available.

• Description: Creates an external-browser OAuth login session for desktop containers such as Electron.

• Request Body:

  {
    "method": "AuthRpc.createExternalOAuthLoginSession",
    "params": {
      "provider": "google"
    }
  }

• Parameters:

  Name	Type	Required	Description
  provider	String	Yes	OAuth provider name, such as google.

• Response:

  {
    "success": true,
    "data": {}
  }

  The exact response shape is determined by OAuthService.createExternalLoginSession(...) and was not inspected here.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "AuthRpc.createExternalOAuthLoginSession",
      "params": {
        "provider": "google"
      }
    }'

POST /api/rpc (Method: AuthRpc.pollExternalOAuthLoginSession)

This method checks whether an external OAuth login session has completed. It returns the consumed login result from the OAuth service.

• Description: Polls an external-browser OAuth login session until it completes.
• Request Body:

// Example hook implementation
export default {
    tenancy: {
        auth: {
            signup: {
                onAfterSignup: async (user, context) => {
                    // Custom post-signup logic (e.g. provision a default project)
                }
            }
        }
    }
};