API: Authentication

These endpoints create and end sessions. They return a bearer token you can use exactly like an API key. For unattended scripts, prefer a dedicated API key over your login token.

POST /auth/register

Creates an account and sends a 6-digit code by email and SMS. The phone number must be an Iranian mobile number and terms_accepted must be true.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required
`name`	string	Yes
`email`	string	Yes
`phone`	string	Yes
`password`	string	Yes
`terms_accepted`	boolean	Yes

Responses

201 Created. Returns: message (string), user_id (integer), otp_channel (string).
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/register \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-name","email":"you@example.com","phone":"09121234567","password":"your-password","terms_accepted":true}'

POST /auth/verify-otp

Confirms the code and returns the user with a bearer token.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`user_id`	integer	Yes
`code`	string	Yes

Responses

200 OK. Returns: user (User), token (string), dashboard (string).
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/verify-otp \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1,"code":"123456"}'

POST /auth/resend-otp

Sends a fresh verification code.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`user_id`	integer	Yes

Responses

200 OK
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/resend-otp \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1}'

Log in

POST /auth/login

Checks email and password. Without two-factor authentication it returns the user and a token. With it on, it returns requires_2fa and an opaque challenge_token to send with the next step (valid 5 minutes, 5 attempts). Accounts that never finished sign-up verification get an email_not_verified error.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`email`	string	Yes
`password`	string	Yes

Responses

200 OK
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'

POST /auth/login/2fa

Sends the challenge_token from the login step and the current 6-digit code (authenticator app, email or SMS) and returns the user and a token. Five wrong attempts invalidate the challenge.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`challenge_token`	string	Yes
`code`	string	Yes

Responses

200 OK. Returns: user (User), token (string), dashboard (string).
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/login/2fa \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"string","code":"123456"}'

Resend the two-factor code

POST /auth/login/2fa/resend

Sends a new code (with the challenge_token) for accounts that use email or SMS as the second factor.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`challenge_token`	string	Yes

Responses

200 OK. Returns: message (string), expires_in_minutes (integer).
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/login/2fa/resend \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"string"}'

Request a password reset link

POST /auth/forgot-password

Emails a reset link if the address belongs to an account. The answer is identical either way.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`email`	string	Yes

Responses

200 OK. Returns: message (string).
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/auth/forgot-password \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Set a new password

POST /auth/reset-password

Uses the emailed token to set a new password. All existing sessions are signed out.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required
`email`	string	Yes
`token`	string	Yes
`password`	string	Yes
`password_confirmation`	string	Yes

Responses

200 OK. Returns: message (string).
422 Validation error, or not allowed in the current state

Example

curl -X POST https://veneshcloud.ir/api/auth/reset-password \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","token":"TOKEN_FROM_EMAIL","password":"your-password","password_confirmation":"your-new-password"}'

Log out

POST /auth/logout

Revokes the token used for the request.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK

Example

curl -X POST https://veneshcloud.ir/api/auth/logout \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Current user

GET /auth/me

Returns the account that owns the token.

Authentication: Send your API key or token as a bearer token.

Responses

200 OK. Returns User.

Example

curl -X GET https://veneshcloud.ir/api/auth/me \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

Log in with a recovery code

POST /account/2fa/recovery-code

Completes a two-factor login with one of your one-time recovery codes, sent together with the challenge_token from the login step.

Authentication: None, this endpoint is public.

Request body (application/json)

Field	Type	Required	Values
`challenge_token`	string	Yes
`recovery_code`	string	Yes

Responses

200 OK. Returns: user (User), token (string), dashboard (string).
422 Validation error, or not allowed in the current state
429 Too many requests

Example

curl -X POST https://veneshcloud.ir/api/account/2fa/recovery-code \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"challenge_token":"string","recovery_code":"RECOVERY_CODE"}'

Objects

Field lists for the objects returned above.

User

Field	Type	Values
`id`	integer
`name`	string
`email`	string
`phone`	string
`avatar_url`	string
`role`	string	`admin`, `support_tech`, `support_finance`, `support_sales`, `customer`
`email_verified`	boolean
`phone_verified`	boolean
`two_factor_enabled`	boolean
`two_factor_method`	string	`totp`, `email`, `sms`
`created_at`	string

API: Authentication

Sign up

Verify the sign-up code

Resend the sign-up code

Log in

Complete a two-factor login

Resend the two-factor code

Request a password reset link

Set a new password

Log out

Current user

Log in with a recovery code

Objects

User