Skip to content
/
Verify Email
Last updated

Verify Email

POST /v1/auth/verify - Verify the 4-digit code sent via email during registration or login. Returns authentication tokens upon successful verification.

POSThttps://api.aitronos.com/v1/auth/verify

Validates the 4-digit verification code sent via email and returns authentication tokens. Used after POST /register or POST /login when email verification is required. The code expires after 5 minutes.

Request Body

email_key string required

Unique identifier received from registration or login endpoint. Used to associate the verification code with the correct user session.

verification_code integer required

4-digit verification code (1000-9999) received via email. Code expires after 5 minutes.

device_information object optional

Device information for session tracking.

Show device_information object properties

device string optional

Device name or browser name (e.g., "Macintosh", "Chrome Browser", "iPhone 14").

platform string optional

Platform type (e.g., "web", "ios", "android").

operating_system string optional

Operating system (e.g., "mac", "windows", "linux", "ios", "android").

device_id string optional

Unique device identifier for tracking sessions across devices.

user_agent string optional

User agent string from the browser or client application.

location string optional

Geographic location.

latitude string optional

Latitude coordinate.

longitude string optional

Longitude coordinate.

Returns

A Verify Response object containing authentication tokens and user information.

token string

JWT access token for API authentication. Include in Authorization: Bearer {token} header.

refreshToken string

JWT refresh token used to obtain new access tokens when the current token expires.

token_type string

Token type, always "bearer".

expires_in integer

Access token expiration time in seconds (typically 86400 for 24 hours).

device_id string | null

Device identifier associated with this session. May be null if device tracking is not enabled.

user object

User information object.

Show user properties

id string

Unique user identifier.

email string

User's email address.

verified boolean

Email verification status. Always true after successful verification.

Bash
curl -X POST "https://api.aitronos.com/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email_key": "0ce5227b-b008-4d24-aa3a-212772ad150d",
    "verification_code": 2290,
    "device_info": {
      "device": "Macintosh",
      "platform": "web",
      "operating_system": "mac",
      "device_id": "b01dcdc9-ee60-42b4-a29d-762ba17ea586"
    }
  }'

Response:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjU5MDQ0NTAsImp0aSI6ImRmODFmZGM3LTQxZjgtNDY4ZC04ZDgxLTJjMDA2NGQwOTIxMSIsInR5cGUiOiJyZWZyZXNoIiwic3ViIjoidXNyXzFlNjBiN2EwMTRlYjRmMGM5ZjMzNWNlMTFlYmMwODE2IiwibmJmIjoxNzY1OTA0NDUwLCJleHAiOjE3Njg0OTY0NTAsImN0eCI6ImdBQUFBQUJwUVpCQ2ktOThySFRKVktXY091dzM2OHAxN2o1SFp3UTNzd1VVTXY0dHhvbWhRbWR2V3k5QUVOclN6LUNhaVdDODFNUEswdUlWV1kwX2hGYTBTelRkZVRyMDNPbXFrOGstMHJCWEZmQ1ZKdWYySklXNWNTUUFmRXRFZmlSbmN3YWpScF9QbE1yWTRrdkdERmxORzhtQVpFMDVtZz09In0.kGvu_w3kdqliLRAHNZSOCNzFvMFrXzrLqWcg7cllDgk",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjU5MDQ0NTAsImp0aSI6IjRkODJhMzIzLWM2YmItNDRjNi1hYWI3LWMwZjZjZWYxNTA2NCIsInR5cGUiOiJhY2Nlc3MiLCJzdWIiOiJ1c3JfMWU2MGI3YTAxNGViNGYwYzlmMzM1Y2UxMWViYzA4MTYiLCJuYmYiOjE3NjU5MDQ0NTAsImV4cCI6MTc2NTk5MDg1MCwiY3R4IjoiZ0FBQUFBQnBRWkJDbUhhdUtsdTdCZDJsbm9DOTRSZ3QzTHZySEUtc0Q5eV9ZLVVuV1dNelN4ZnVQZmYzU2NWbWJkM0NvbTM5MWx3SmQ2N1VNSFdwMTZJZGlJLU5qQmpmRFN2TE5uX0RIWDFrZ29kVDBkb2gzUHFacUh2N1RuVEFPYUZVT0tNVk5hQ1Y1S21uR2FyMjg4MmNNZlM2VjlHOHR3PT0ifQ.dbdxeqnt1yDhLFDbGissq0HMFOZa_De2stnm-LtskJg",
  "token_type": "bearer",
  "expires_in": 86400,
  "device_id": null,
  "user": {
    "id": "usr_1e60b7a014eb4f0c9f335ce11ebc0816",
    "email": "phillip.loacker@aitronos.com",
    "verified": true
  }
}

Response

Use Cases

After Registration

  1. User calls POST /register with email and password
  2. User receives email_key in response
  3. User receives 4-digit code via email
  4. User calls POST /v1/auth/verify with email_key and code
  5. User receives authentication tokens

After Login

  1. User calls POST /login with email and password
  2. User receives email_key in response
  3. User receives 4-digit code via email
  4. User calls POST /v1/auth/verify with email_key and code
  5. User receives authentication tokens

Not For Password Reset

❌ Do not use this endpoint for password reset verification. Use POST /v1/auth/password/reset/verify instead.

Error Handling

Error CodeStatusDescription
VERIFICATION_CODE_INVALID422Wrong code entered
VERIFICATION_CODE_EXPIRED422Code is older than 5 minutes
INVALID_VERIFICATION_TYPE422Wrong flow (e.g., using password reset code)
VERIFICATION_NOT_FOUND404Invalid or expired email_key
USER_ALREADY_EXISTS409Email already registered (during registration flow)

Security Features

  • Time-limited codes: Verification codes expire after 5 minutes
  • One-time use: Codes are marked as used after successful verification
  • Session tracking: Device information helps track active sessions
  • Rate limiting: Prevents brute force attacks on verification codes
  • Automatic cleanup: Expired codes are automatically cleaned up

Best Practices

  1. Store email_key securely: Keep email_key in memory or secure session storage
  2. Show expiry timer: Display countdown showing when the code expires (5 minutes)
  3. Handle errors gracefully: Show user-friendly error messages
  4. Request new code: Provide option to resend code if expired (use POST /v1/user/resend-email)
  5. Store tokens securely: Never store tokens in localStorage for production apps
  6. Clear sensitive data: Don't store verification code in browser storage
  7. Redirect after success: Redirect to dashboard or main app after successful verification
Previous page
Next page