Skip to main content

​
Endpoint

POST /recipe/signinup
Authenticates a user with a third-party provider (social login). This endpoint handles both signing in existing users and signing up new users in a single operation.

​
Request Headers

​
api-key
string
required
Your SuperTokens API key for authentication
​
cdi-version
string
Core Driver Interface version (e.g., “2.7”, “3.0”, “4.0”, “5.0”)

​
Request Body

​
thirdPartyId
string
required
The identifier for the third-party provider (e.g., “google”, “facebook”, “github”)
​
thirdPartyUserId
string
required
The user’s unique identifier from the third-party provider
​
email
object
required
Email information object containing:

​
Request Example

curl -X POST https://your-domain.com/recipe/signinup \
  -H "api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "thirdPartyId": "google",
    "thirdPartyUserId": "115557735426603809847",
    "email": {
      "id": "[email protected]",
      "isVerified": true
    }
  }'

​
Response

​
Success Response

​
status
string
Returns "OK" on successful authentication
​
createdNewUser
boolean
true if a new user account was created, false if an existing user signed in
​
user
object
User information object containing:
​
recipeUserId
string
The recipe-specific user ID for this login method (CDI 4.0+)

​
Success Response Example

{
  "status": "OK",
  "createdNewUser": false,
  "user": {
    "id": "fa3b009d-597c-4a67-94d8-7e3aa48f4f63",
    "email": "[email protected]",
    "timeJoined": 1678901234567,
    "thirdParty": {
      "id": "google",
      "userId": "115557735426603809847"
    },
    "tenantIds": ["public"],
    "loginMethods": [
      {
        "recipeId": "thirdparty",
        "recipeUserId": "fa3b009d-597c-4a67-94d8-7e3aa48f4f63",
        "thirdParty": {
          "id": "google",
          "userId": "115557735426603809847"
        },
        "email": "[email protected]",
        "timeJoined": 1678901234567,
        "verified": true
      }
    ]
  },
  "recipeUserId": "fa3b009d-597c-4a67-94d8-7e3aa48f4f63"
}

​
Error Response

​
status
string
Returns "EMAIL_CHANGE_NOT_ALLOWED_ERROR" when email cannot be changed
​
reason
string
Error reason description

​
Error Response Example

{
  "status": "EMAIL_CHANGE_NOT_ALLOWED_ERROR",
  "reason": "Email already associated with another primary user."
}

​
Behavior Details

​
Sign Up vs Sign In

This endpoint automatically determines whether to create a new user or sign in an existing user based on:
  1. Existing User: If a user with the same thirdPartyId and thirdPartyUserId exists, the user is signed in
  2. New User: If no matching user exists, a new user account is created

​
Email Verification

The isVerified flag in the email object controls email verification:
  • true: The email is marked as verified (trusted provider)
  • false: The email requires manual verification
Email verification support was added in CDI version 4.0. For earlier versions, emails are not automatically verified.

​
Account Linking

When account linking is enabled (CDI 4.0+), this endpoint may:
  • Link the social account to an existing user with the same email
  • Prevent email changes if the email is already associated with another primary user

​
Multi-tenancy

This API is tenant-specific. The tenant is determined by:
  • The tenantId header or query parameter
  • The default tenant if not specified
Third-party login must be enabled for the tenant. If disabled, the API will return a BadPermissionException.

​
Version Compatibility

FeatureCDI VersionNotes
Basic sign in/up2.7+Core functionality
Email verification4.0+isVerified field support
Account linking4.0+Automatic account linking
Recipe user ID4.0+Returns recipeUserId field
Tenant IDs3.0+Multi-tenancy support

​
Common Integration Pattern

// After OAuth callback
const response = await fetch('https://your-domain.com/recipe/signinup', {
  method: 'POST',
  headers: {
    'api-key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    thirdPartyId: 'google',
    thirdPartyUserId: oauthUserInfo.sub,
    email: {
      id: oauthUserInfo.email,
      isVerified: oauthUserInfo.email_verified
    }
  })
});

const data = await response.json();

if (data.status === 'OK') {
  console.log('User authenticated:', data.user.id);
  console.log('New user:', data.createdNewUser);
  // Create session for the user
} else if (data.status === 'EMAIL_CHANGE_NOT_ALLOWED_ERROR') {
  console.error('Email conflict:', data.reason);
}

Create Session

Create a session after authentication

Get User

Retrieve user information

​
Source Code Reference

Implementation: View source

Build docs developers (and LLMs) love

Get started for freeTalk to us