# Create a new access token

Authenticates a user and issues a new access token. When API token verification is enabled (server configuration), users with enhanced security (2FA enabled or linked social providers like Google/Apple) must complete additional verification. Users with 2FA provide their authenticator code via two_factor_code. Users with linked social providers (without 2FA) receive a 6-digit OTP via email and provide it via otp_code.

Endpoint: POST /v1/auth/tokens
Version: 1.0.0

## Request fields (application/json):

  - `email` (string, required)
    User's email address
    Example: "user@nextvisit.app"

  - `password` (string, required)
    User's password
    Example: "secureP@ssw0rd!"

  - `device_name` (string, required)
    Name of the device requesting the token
    Example: "iPhone 14 Pro"

  - `two_factor_code` (string)
    TOTP code from authenticator app (required for users with 2FA enabled when API token verification is active). Recovery codes can also be used.
    Example: "123456"

  - `otp_code` (string)
    6-digit verification code sent via email (required for users with linked social providers when API token verification is active)
    Example: "123456"

## Response 200 fields (application/json):

  - `status` (string, required)
    Status of the token request
    Example: "success"

  - `token` (string, required)
    Authentication token value
    Example: "nv-sk-2|4qrD6iCn5FYhHyrdVX1IE4kk6RWg091WpboNklOC"

  - `token_id` (integer, required)
    Unique identifier for the token
    Example: 123

  - `user` (object, required)
    Basic information about the authenticated user

  - `user.id` (integer)
    User's unique identifier
    Example: 1

  - `user.name` (string)
    User's full name
    Example: "John Doe"

  - `user.current_team_id` (integer)
    ID of the user's current team
    Example: 5

  - `user.email` (string)
    User's email address
    Example: "john.doe@example.com"

  - `team` (object, required)
    Basic information about the user's current team

  - `team.id` (integer)
    Team's unique identifier
    Example: 5

  - `team.name` (string)
    Name of the team
    Example: "Medical Practice"

## Response 403 fields (application/json):

  - `status` (string, required)
    Status indicating verification is required
    Enum: "verification_required"

  - `verification_type` (string, required)
    Type of verification required
    Enum: "two_factor", "email_otp"

  - `message` (string, required)
    Human-readable message explaining what is required
    Example: "Please provide your two-factor authentication code."

## Response 422 fields (application/json):

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (object)
    Detailed validation errors by field
    Example: {"email":["The email must be a valid email address","The email has already been taken"],"password":["The password must be at least 8 characters"],"template_name":["This field is required"]}