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

# Authentication — Register, Login, and Bearer Tokens

> Learn how to create a CogNerd account, obtain a session token by logging in, and authenticate every API request using the Authorization: Bearer header.

Every CogNerd API request that accesses your data requires a valid session token. You obtain a token by logging in with your email and password. Once you have a token, you pass it in the `Authorization` header on every subsequent request. This page walks through registration, login, and authenticated calls — with working copy-paste examples in both curl and JavaScript.

## Register an account

Send a `POST` request to `/api/auth/register` with your name, email, and password. Registration creates your account and logs you in automatically — the response includes your session token so you can start making authenticated requests immediately.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cognerd.in/api/auth/register \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Jane Smith",
      "email": "you@example.com",
      "password": "your-password"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.cognerd.in/api/auth/register", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      name: "Jane Smith",
      email: "you@example.com",
      password: "your-password",
    }),
  });

  const data = await response.json();
  const token = data.token;
  ```
</CodeGroup>

### Request parameters

<ParamField body="name" type="string" required>
  Your full name. Stored on your profile and visible in the dashboard.
</ParamField>

<ParamField body="email" type="string" required>
  The email address you want to use as your login credential. Must be unique.
</ParamField>

<ParamField body="password" type="string" required>
  Your chosen password. Must be at least 8 characters. CogNerd never stores plaintext passwords.
</ParamField>

### Response

```json theme={null}
{
  "token": "eyJhbGci...",
  "user": {
    "id": "usr_123",
    "email": "you@example.com"
  }
}
```

<ResponseField name="token" type="string">
  Your session token. Use this in the `Authorization: Bearer` header for all authenticated requests.
</ResponseField>

<ResponseField name="user.id" type="string">
  Your unique user ID.
</ResponseField>

<ResponseField name="user.email" type="string">
  The email address associated with your account.
</ResponseField>

***

## Log in

If you already have an account, send a `POST` request to `/api/auth/login`. A successful login returns a fresh session token.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.cognerd.in/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email": "you@example.com", "password": "your-password"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.cognerd.in/api/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "you@example.com",
      password: "your-password",
    }),
  });

  const data = await response.json();
  const token = data.token;
  ```
</CodeGroup>

### Request parameters

<ParamField body="email" type="string" required>
  The email address you registered with.
</ParamField>

<ParamField body="password" type="string" required>
  Your account password.
</ParamField>

### Response

```json theme={null}
{
  "token": "eyJhbGci...",
  "user": {
    "id": "usr_123",
    "email": "you@example.com"
  }
}
```

<ResponseField name="token" type="string">
  Your session token. Store this securely — you will send it with every authenticated request.
</ResponseField>

<ResponseField name="user.id" type="string">
  Your unique user ID.
</ResponseField>

<ResponseField name="user.email" type="string">
  The email address associated with your account.
</ResponseField>

***

## Authenticate requests

Pass your token in the `Authorization` header as a Bearer token on every protected request.

```
Authorization: Bearer YOUR_TOKEN
```

### Example — fetch your user profile

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.cognerd.in/api/auth/me \
    -H "Authorization: Bearer eyJhbGci..."
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.cognerd.in/api/auth/me", {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });

  const { user } = await response.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "user": {
    "id": 42,
    "name": "Jane Smith",
    "email": "you@example.com",
    "phone": null,
    "image": null,
    "plan": "basic",
    "createdAt": "2024-01-10T08:00:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

<ResponseField name="user.id" type="number">
  Your numeric user ID.
</ResponseField>

<ResponseField name="user.name" type="string">
  Your display name.
</ResponseField>

<ResponseField name="user.email" type="string">
  Your registered email address.
</ResponseField>

<ResponseField name="user.plan" type="string">
  Your active subscription plan (e.g., `"monitor"`, `"optimize"`, `"enterprise"`).
</ResponseField>

***

## Token expiry and refresh

Session tokens are valid for **7 days**. The expiry is automatically extended by 1 day on each successful authenticated request, so an active session stays alive without any action from you.

If your token has expired, re-authenticate using `POST /api/auth/login` to get a fresh one.

<Note>
  There is no separate refresh token endpoint. Simply log in again when your session expires.
</Note>

***

## Authentication errors

When a request is missing a token or the token is invalid/expired, the API responds with a `401` status code.

```json theme={null}
{
  "error": {
    "message": "Please log in to use this feature",
    "code": "UNAUTHORIZED",
    "statusCode": 401,
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}
```

<ResponseField name="error.code" type="string">
  Always `"UNAUTHORIZED"` for authentication failures.
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable description of why the request was rejected.
</ResponseField>

<Warning>
  Never expose your session token in client-side code, public repositories, or logs. Treat it with the same care as a password.
</Warning>

***

## Keeping your token secure

A few recommendations for API integrations:

* Store tokens in environment variables, a secrets manager, or an encrypted credential store — never hard-code them in source files.
* Rotate tokens by logging out (`POST /api/auth/logout`) and logging in again if you suspect a token has been compromised.
* Use HTTPS at all times. The production endpoint (`https://api.cognerd.in`) enforces TLS automatically.