> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tktchurch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create New Account

> Create a new user account with email verification

<Note>
  This is a public endpoint that does not require authentication.
</Note>

### Request Body

<ParamField body="email" type="string" required={true}>
  Email address for the new account. Must be unique in the system.
</ParamField>

<ParamField body="password" type="string" required={true}>
  Password for the account. Must be at least 6 characters long.
</ParamField>

<ParamField body="firstName" type="string" required={false}>
  User's first name. Maximum 50 characters.
</ParamField>

<ParamField body="lastName" type="string" required={false}>
  User's last name. Maximum 50 characters.
</ParamField>

### Response

A successful request returns HTTP 201 Created status. The user will receive:

1. A verification email with a token to verify their email address
2. A welcome email

<Note>
  The account is created with:

  * Status: `active`
  * Provider: `local`
  * Role: `Member` (default role)
  * `emailVerified`: false
  * `phoneNumberVerified`: false
</Note>

### Error Responses

<ResponseField name="error" type="object">
  Error details when the request fails

  <Expandable title="Error Object">
    <ResponseField name="status" type="integer">
      HTTP status code
    </ResponseField>

    <ResponseField name="reason" type="string">
      Error message explaining why the request failed
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Common error cases:

  * 400 Bad Request: Invalid email format or password too short
  * 400 Bad Request: Email already exists
  * 500 Internal Server Error: Default role not found
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tktchurch.com/v1/auth/signup" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "john.doe@example.com",
      "password": "securePassword123",
      "firstName": "John",
      "lastName": "Doe"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tktchurch.com/v1/auth/signup', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'john.doe@example.com',
      password: 'securePassword123',
      firstName: 'John',
      lastName: 'Doe'
    })
  });

  const data = await response.json();
  if (!response.ok) {
    throw new Error(data.error.reason);
  }
  ```

  ```swift Swift theme={null}
  struct SignupRequest: Encodable {
      let email: String
      let password: String
      let firstName: String?
      let lastName: String?
  }

  let request = SignupRequest(
      email: "john.doe@example.com",
      password: "securePassword123",
      firstName: "John",
      lastName: "Doe"
  )

  var urlRequest = URLRequest(url: URL(string: "https://api.tktchurch.com/v1/auth/signup")!)
  urlRequest.httpMethod = "POST"
  urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
  urlRequest.httpBody = try? JSONEncoder().encode(request)

  let (data, response) = try await URLSession.shared.data(for: urlRequest)
  guard let httpResponse = response as? HTTPURLResponse else {
      throw URLError(.badServerResponse)
  }

  if httpResponse.statusCode == 201 {
      print("Account created successfully")
  } else {
      let error = try JSONDecoder().decode(ErrorResponse.self, from: data)
      throw error
  }
  ```

  ```kotlin Kotlin theme={null}
  data class SignupRequest(
      val email: String,
      val password: String,
      val firstName: String?,
      val lastName: String?
  )

  val client = OkHttpClient()

  val request = SignupRequest(
      email = "john.doe@example.com",
      password = "securePassword123",
      firstName = "John",
      lastName = "Doe"
  )

  val requestBody = request.toJson().toRequestBody("application/json".toMediaType())

  val httpRequest = Request.Builder()
      .url("https://api.tktchurch.com/v1/auth/signup")
      .post(requestBody)
      .header("Content-Type", "application/json")
      .build()

  client.newCall(httpRequest).execute().use { response ->
      if (!response.isSuccessful) {
          val error = response.body?.string()?.fromJson<ErrorResponse>()
          throw Exception(error?.reason ?: "Unknown error")
      }
      // Handle success
  }
  ```

  ```typescript React Native theme={null}
  import axios from 'axios';

  interface SignupRequest {
    email: string;
    password: string;
    firstName?: string;
    lastName?: string;
  }

  const signup = async (data: SignupRequest) => {
    try {
      const response = await axios.post(
        'https://api.tktchurch.com/v1/auth/signup',
        data,
        {
          headers: {
            'Content-Type': 'application/json',
          },
        }
      );
      
      if (response.status === 201) {
        // Handle success
        return response.data;
      }
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new Error(error.response?.data?.error?.reason || 'Signup failed');
      }
      throw error;
    }
  };

  // Usage
  await signup({
    email: 'john.doe@example.com',
    password: 'securePassword123',
    firstName: 'John',
    lastName: 'Doe'
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Success theme={null}
  {
    "status": 201,
    "message": "Account created successfully. Please check your email for verification."
  }
  ```

  ```json 400 Email Exists theme={null}
  {
    "error": {
      "status": 400,
      "reason": "Email already exists"
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "status": 400,
      "reason": "Validation error: password must be at least 6 characters"
    }
  }
  ```

  ```json 500 Role Error theme={null}
  {
    "error": {
      "status": 500,
      "reason": "Default role not found"
    }
  }
  ```
</ResponseExample>