Sign In
Authenticate users with email and password, initiating two-factor authentication flow
🔓 USER AUTHENTICATION
Sign In
Authenticate users with secure credential validation and initiate two-factor authentication verification.
Two-Step Process
Sign-in is a two-step process: first authenticate with email/password, then verify with 2FA code.
Overview
The signin mutation authenticates users using their email and password credentials. Upon successful validation, the system sends a 2FA code via the user's configured method (app, email, or SMS) for additional security verification.
GraphQL Schema
mutation {
signin(
email: String!
password: String!
): Credentials!
}
type Credentials {
status: String
token: String
twoStep: [String]
}Parameters
String
User's registered email address for account identification.
password
RequiredString
User's account password for authentication.
Return Type: Credentials
statusStringAuthentication result: "Success" or "Failed"
tokenStringTemporary token for 2FA step (not JWT). Contains error message if failed.
twoStep[String]Array of configured 2FA methods: ['app', 'email'] or ['email', 'phone']
Response States
Success Response
SuccessCredentials validated successfully. 2FA code sent via configured method(s). Proceed to 2FA verification.
"Success"Temporary 2FA token["app", "email"]Error Responses
password mismatchIncorrect password provided. Status is "Failed" and token contains error message.
please verifyAccount exists but email not verified. User must complete email verification first.
Please set 2FAAccount verified but 2FA not configured. User must set up two-factor authentication.
2FA ErrorError generating or sending 2FA code. Contact support if error persists.
Example Usage
Request
mutation SignInUser {
signin(
email: "demouser@nyyu.io"
password: "38f@3n102du/qA!"
) {
status
token
twoStep
}
}Successful Response
{
"data": {
"signin": {
"status": "Success",
"token": "temp_2fa_token_xyz123",
"twoStep": ["app", "email"]
}
}
}2FA Code Sent
2FA codes have been sent via app and email. Proceed to the 2FA verification step.
Password Mismatch
{
"data": {
"signin": {
"status": "Failed",
"token": "password mismatch",
"twoStep": null
}
}
}Authentication Failed
Incorrect password. Please verify your credentials and try again.
Unverified Account
{
"data": {
"signin": {
"status": "Failed",
"token": "please verify",
"twoStep": null
}
}
}Verification Required
Email not verified. Check your inbox for the verification code.
Authentication Flow
Complete Sign-In Process
1️⃣
Submit Credentials
User enters email and password through your sign-in form
mutation signin(email, password)2️⃣
Receive 2FA Token
System validates credentials and returns temporary token with 2FA methods
3️⃣
2FA Verification
Redirect user to 2FA page to enter code from their configured method
→ confirm2FA(email, token, code)4️⃣
Receive JWT Token
After successful 2FA, receive JWT token for authenticated API requests
JWT token → Store securely → Make authenticated requestsImplementation Example
Frontend Integration
// Example: Sign-in flow handler
async function handleSignIn(credentials) {
try {
const result = await graphqlClient.mutate({
mutation: gql`
mutation SignIn($email: String!, $password: String!) {
signin(email: $email, password: $password) {
status
token
twoStep
}
}
`,
variables: {
email: credentials.email,
password: credentials.password
}
});
const { status, token, twoStep } = result.data.signin;
if (status === "Success") {
// Store temporary token and 2FA methods for next step
sessionStorage.setItem('temp2FAToken', token);
sessionStorage.setItem('twoStepMethods', JSON.stringify(twoStep));
sessionStorage.setItem('userEmail', credentials.email);
// Redirect to 2FA verification page
router.push('/verify-2fa');
showNotification(`2FA code sent via ${twoStep.join(' and ')}`);
} else {
// Handle various error states
handleSignInError(token);
}
} catch (error) {
console.error("Sign-in failed:", error);
showError("Authentication failed. Please try again.");
}
}
function handleSignInError(errorMessage) {
switch(errorMessage) {
case "password mismatch":
showError("Incorrect password. Please try again.");
break;
case "please verify":
showError("Please verify your email first.");
router.push('/verify-email');
break;
case "Please set 2FA":
showError("Please set up 2FA for your account.");
router.push('/setup-2fa');
break;
case "2FA Error":
showError("Error sending 2FA code. Please try again or contact support.");
break;
default:
showError("Sign-in failed. Please try again.");
}
}Use Cases
User Authentication
Primary login method for verified users to access their accounts securely
Multi-Factor Auth
Initiate two-factor authentication flow for enhanced account security
Multiple 2FA Methods
Support users with multiple configured 2FA options (app + email or email + phone)
Session Management
Obtain temporary token for 2FA verification before receiving final JWT token
Best Practices
🔒 Token Handling
The initial token is temporary for 2FA verification only. Store it securely in session storage, not local storage
🎯 Error Handling
Implement specific UI responses for each error state to guide users through resolution
📱 2FA Method Display
Show users which 2FA methods are available and let them choose their preferred verification method
🔐 Security First
Never store passwords client-side and always use HTTPS for credential transmission
⏰ Token Expiry
The temporary 2FA token has limited validity. Prompt users to complete 2FA verification promptly
🚀 User Flow
Automatically redirect users based on status: unverified → verify page, no 2FA → setup page, success → 2FA page