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

# POST /v1/auth/log — Record a Security Sign-in Event

> Record a login or signup security event for the authenticated user. Adds IP geolocation and device info. Sends a security alert email when event is login.

Record a security event immediately after a successful sign-in. The server enriches the entry with the caller's IP address, geolocation data, and device information, then stores the record in the security audit log. When `event` is `"login"`, the user also receives an in-app notification and a security email alerting them to the new sign-in.

**POST** `/v1/auth/log`

Requires a Bearer token in the `Authorization` header.

## Request

<ParamField body="event" type="string" required>
  The type of authentication event. Accepted values: `"login"` or `"signup"`.
</ParamField>

<ParamField body="fingerprint" type="string">
  An optional device fingerprint string. Stored alongside the log entry for security auditing.
</ParamField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.nyotaimara.com/v1/auth/log" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{"event": "login", "fingerprint": "abc123xyz"}'
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean" required>
  `true` when the event was logged. The server returns `200` even when logging fails internally, to avoid breaking the user's authentication flow.
</ResponseField>

```json theme={null}
{
  "success": true
}
```

<Note>
  **Behaviour on login**

  When `event` is `"login"`, the server sends the authenticated user both an in-app notification and a security email containing the detected device, location, IP address, and timestamp. No notification is sent for `"signup"` events.

  **Error cases**

  | Status               | Condition                                                    |
  | -------------------- | ------------------------------------------------------------ |
  | 401                  | Missing or invalid Bearer token.                             |
  | 200 `success: false` | Logging failed internally. The user's session is unaffected. |
</Note>