Aller au contenu principal

Build email and password authentication

Use these JSON endpoints when you provide your own form. Keep client/workspace context consistent across signup, verification and login. For a form hosted by SyAuth, use OAuth hosted sign-in.

Choose this guide if you are testing direct API requests or a developer is building your own login form. The commands below display responses in a terminal; they do not display a registration page, login screen or success page in the browser. To try those screens without an app, use the manual hosted-login test.

Replace the placeholders and sample email/password directly, keeping the surrounding quotes. No environment setup is required. Windows examples use Command Prompt (CMD). Follow the steps in order: verification uses the user created in step 1, and profile access uses the token returned in step 3.

Before you start​

Complete dashboard setup, including an application and an email_verification template in the same workspace. Prepare these values:

Value in the examplesWhat to use
YOUR_PUBLIC_CLIENT_IDThe application's OAuth client_id from Applications, not the configuration record's id. The oauth_client field uses this value even for a confidential client.
[email protected]Replace every occurrence with the same real email address you control. The example address cannot receive mail.
ExamplePass!7264XReplace every occurrence with your test user's password. For SyAuth-managed users, use at least 12 characters, including uppercase, lowercase, a number and a special character. Set confirm_password to the same value.
YOUR_REGISTRATION_API_KEYA separately provisioned registration API key, only if using the JSON signup request below.
CODE_FROM_EMAILThe code sent after creating this user or resending verification. Keep it as a string, including any leading zeros.
YOUR_APPLICATION_TOKENThe token from a completed login in step 3; it is not your developer token or client secret.

Keep the same email and oauth_client through signup, verification, login and password recovery.

Run commands in Terminal on macOS/Linux or Command Prompt on Windows. Use the tab for your system, copy the whole command after replacing sample values, and press Enter. The first API call guide explains how to check that curl is available. Each response starts with an HTTP status and then a JSON body. If a step fails, read the error and correct it before running the next step.

1. Prepare a user​

Choose one way to create the test user:

  • Dashboard or management API: create a user under Users in the intended workspace and set a password. To explicitly supply the intended OAuth client, use the developer user-management request, which also requests verification email. Then continue at step 2; do not also submit the signup request below for that email.
  • Your own signup form: obtain the registration API key above and send the following request from your application server. Your browser form submits to your own server so the registration key stays there.

If you do not have a registration key yet, use the dashboard/management path to test verification and login. Hosted signup is also available through the hosted sign-in flow.

curl -i "https://api.syauth.com/e/v1/register/" \
  -H "X-API-Key: YOUR_REGISTRATION_API_KEY" \
  -H 'Content-Type: application/json' --data-raw '{"email":"[email protected]","password":"ExamplePass!7264X","confirm_password":"ExamplePass!7264X","oauth_client":"YOUR_PUBLIC_CLIENT_ID","first_name":"Alex","last_name":"Developer"}'

Replace the sample email/password. With the SyAuth user store, expect 201 and requires_verification: true. Custom-database registration has different verification behavior; inspect its response. A workspace API token or developer token is not a registration key.

For the standard user store, requires_verification: true means the next action is to check the user's mailbox and complete step 2. A 201 response confirms registration; it does not confirm that the email arrived. If you created the user through the dashboard instead, check its verification status and continue at step 2. Creating the user alone does not sign it in.

2. Verify the email​

If the user is already marked email verified, continue at step 3. Otherwise, replace CODE_FROM_EMAIL with the actual code delivered to the mailbox used in step 1. Use the same email and OAuth client:

curl -i "https://api.syauth.com/e/v1/email/verify/" \
  -H 'Content-Type: application/json' --data-raw '{"email":"[email protected]","code":"CODE_FROM_EMAIL","oauth_client":"YOUR_PUBLIC_CLIENT_ID"}'

Expect 200 with {"message":"Email verified successfully"}. If you need a new code, send this request, then retry verification with the code from the new email:

curl -i "https://api.syauth.com/e/v1/email/verify/resend/" \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"[email protected]","oauth_client":"YOUR_PUBLIC_CLIENT_ID"}'

See email troubleshooting when delivery fails. A verification code is sent by SyAuth; do not generate it yourself or reuse a password-reset code here.

3. Sign in​

Use the verified application's user email and password from step 1. Your dashboard account credentials do not sign in this user.

curl -i "https://api.syauth.com/e/v1/login/" \
  -H 'Content-Type: application/json' --data-raw '{"email":"[email protected]","password":"ExamplePass!7264X","oauth_client":"YOUR_PUBLIC_CLIENT_ID","remember_me":false}'

A completed login returns user data, token, refresh_token, and message: "Login successful". Copy the full token value from the JSON response for step 4. If mfa_required is true, login is pending: use mfa_ticket and the available methods to complete the challenge. Do not create an authenticated application session from a challenge response. Review MFA availability before enabling it.

For the first test without MFA, the expected result is a completed login with token. If instead you see mfa_required, the command has reached an extra sign-in check, not completed login. Follow the supported MFA flow or ask the developer responsible for that configuration; do not copy the ticket into the profile request as a token.

4. Fetch the profile​

Use the value returned in token:

curl -i "https://api.syauth.com/e/v1/user/profile/" \
  -H "Authorization: Bearer YOUR_APPLICATION_TOKEN"

Expect 200 with this application user's profile. Store authentication state according to your application architecture; do not log tokens or include them in URLs. These application tokens cannot be refreshed using the OAuth token endpoint; use the OAuth flow if you need its documented refresh lifecycle.

Check that the returned user ID/email belongs to your test user. You have completed the basic API test when signup or existing-user preparation, verification, login and profile retrieval all succeed. The password-recovery test below is a separate check; it changes this test user's password.

5. Test password recovery​

Create the workspace's reset_password email template first. Request a reset for the same user and client:

curl -i "https://api.syauth.com/e/v1/password/reset/" \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"[email protected]","oauth_client":"YOUR_PUBLIC_CLIENT_ID"}'

Generic HTTP 200 responses intentionally do not reveal whether an account exists and do not prove email delivery. Copy the code from the password-reset email into RESET_CODE_FROM_EMAIL. Replace YOUR_NEW_PASSWORD in both fields with the same new password meeting the policy above, then submit:

curl -i "https://api.syauth.com/e/v1/password/reset/confirm/" \
  -H 'Content-Type: application/json' \
  --data-raw '{"email":"[email protected]","code":"RESET_CODE_FROM_EMAIL","new_password":"YOUR_NEW_PASSWORD","confirm_password":"YOUR_NEW_PASSWORD","oauth_client":"YOUR_PUBLIC_CLIENT_ID"}'

After a successful reset, repeat step 3 using the new password. A completed login with that password is the final check that recovery worked. Verification codes and reset codes have different purposes; use the code from the matching email.

Profile changes and common errors​

Authenticated password changes use /user/password/update/; profile PATCH does not accept passwords. Passwords for SyAuth-managed users must meet the service policy, including at least 12 characters and uppercase, lowercase, numeric and special characters. Display returned validation errors rather than assuming length alone is sufficient.

Where you are stuckNext action
Signup asks for an API keyObtain a registration key or use the dashboard/management test-user path in step 1
Account already existsUse verification/login for that user; do not repeat signup
Verification email is missingCheck your real recipient address, workspace, client and template; use the resend request above
Code is invalid or expiredRequest a fresh code for the same purpose, email and client, then use it before expiry
Profile returns 401Use the full token from a completed application login, keeping Authorization: Bearer

See the authentication reference for schemas, status codes and custom-database variations.