> For the complete documentation index, see [llms.txt](https://docs.blog-api.codewithsadee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blog-api.codewithsadee.com/authentication.md).

# Authentication

This API uses JSON Web Tokens (JWT) for securing endpoints. It employs a two-token strategy: an Access Token and a Refresh Token.

## Access Token

* **Usage:** Required for accessing protected API endpoints.
* **Format:** Standard JWT.
* **Transmission:** Must be included in the `Authorization` header of your request using the `Bearer` scheme.

```http
  Authorization: Bearer <your_access_token>
```

* **Lifetime:** Access tokens have a predefined expiration time (configured on the server, e.g., 15 minutes). Once expired, you'll receive a `401 Unauthorized` error.
* **Obtaining:** Received upon successful registration (`/auth/register`) or login (`/auth/login`). Can be renewed using a valid Refresh Token (`/auth/refresh-token`).

## Refresh Token

* **Usage:** Used to obtain a new Access Token when the current one expires, without requiring the user to log in again.
* **Format:** Standard JWT.
* **Transmission:** Automatically handled via an `HttpOnly`, `Secure` (in production), `SameSite=Strict` cookie named `refreshToken`. You generally don't need to manage this token directly in your client-side code.
* **Lifetime:** Refresh tokens have a longer expiration time (configured on the server, e.g., 7 days).
* **Obtaining:** Set automatically as a cookie upon successful registration or login.
* **Invalidation:** Deleted from the server and the cookie is cleared upon logout (`/auth/logout`).

## Authentication Flow

1. **Register or Login:** Call `/auth/register` or `/auth/login` with valid credentials.
   * Receive an `accessToken` in the response body.
   * Receive a `refreshToken` set as an HttpOnly cookie.
2. **Access Protected Resources:** Make requests to other API endpoints, including the `accessToken` in the `Authorization: Bearer <token>` header.
3. **Handle Expired Access Token:** If a request returns a `401 Unauthorized` error indicating an expired access token:
   * Call `POST /auth/refresh-token`. This endpoint uses the `refreshToken` cookie automatically sent by the browser.
   * Receive a new `accessToken` in the response.
   * Retry the original request with the new `accessToken`.
4. **Handle Expired Refresh Token:** If the `/auth/refresh-token` endpoint returns a `401 Unauthorized` error, the refresh token has expired or is invalid. The user must log in again via `/auth/login`.
5. **Logout:** Call `POST /auth/logout`. This requires both the `accessToken` (in the header) and the `refreshToken` (in the cookie) to be valid. It invalidates the refresh token on the server and clears the cookie.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blog-api.codewithsadee.com/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.