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

# Authentication API — Register, Login, Reset

> Developer Console auth endpoints: account creation, login, token refresh, password reset with OTP, and password change. Returns JWT tokens.

The authentication endpoints manage developer accounts for the Predexy Developer Console. Register with an email address and password to get JWT tokens you can use to call session-protected endpoints and create API keys. Tokens are returned in the response body and simultaneously set as httpOnly cookies, so both server-side and browser-based integrations are supported.

## Endpoints

| Method | Path                           | Description                               |
| ------ | ------------------------------ | ----------------------------------------- |
| `POST` | `/api/v1/auth/register`        | Create a new developer account            |
| `POST` | `/api/v1/auth/login`           | Log in with email and password            |
| `POST` | `/api/v1/auth/logout`          | Clear auth cookies                        |
| `POST` | `/api/v1/auth/refresh`         | Exchange refresh token for new tokens     |
| `GET`  | `/api/v1/auth/me`              | Get current user profile                  |
| `POST` | `/api/v1/auth/forgot-password` | Send a password reset OTP by email        |
| `POST` | `/api/v1/auth/verify-otp`      | Verify OTP and receive a reset token      |
| `POST` | `/api/v1/auth/reset-password`  | Set a new password using the reset token  |
| `POST` | `/api/v1/auth/change-password` | Change password for an authenticated user |

## Token types

| Token           | Expiry     | How to use                                                                                 |
| --------------- | ---------- | ------------------------------------------------------------------------------------------ |
| `access_token`  | 15 minutes | Pass as `Authorization: Bearer <token>` or send automatically via the `pdx_access` cookie  |
| `refresh_token` | 7 days     | Send via the `pdx_refresh` cookie or `Authorization` header to `POST /api/v1/auth/refresh` |

***

## Register

```
POST https://api.predexy.com/api/v1/auth/register
```

Creates a new developer account. Returns an `AuthResponse` with tokens on success.

### Request body

<ParamField body="email" type="string" required>
  Developer email address.
</ParamField>

<ParamField body="password" type="string" required>
  Password. Minimum 8 characters.
</ParamField>

<ParamField body="name" type="string" required>
  Full name. 1–100 characters.
</ParamField>

### Example request

```bash cURL theme={null}
curl -X POST https://api.predexy.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@company.com",
    "password": "securepassword",
    "name": "Jane Doe"
  }'
```

### AuthResponse fields

<ResponseField name="data.id" type="string" required>
  User UUID.
</ResponseField>

<ResponseField name="data.email" type="string" required>
  User email address.
</ResponseField>

<ResponseField name="data.name" type="string" required>
  User display name.
</ResponseField>

<ResponseField name="tokens.access_token" type="string" required>
  JWT access token. Valid for 15 minutes.
</ResponseField>

<ResponseField name="tokens.refresh_token" type="string" required>
  JWT refresh token. Valid for 7 days. Use to obtain new access tokens without re-entering credentials.
</ResponseField>

### Sample response

```json theme={null}
{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "email": "dev@company.com",
    "name": "Jane Doe"
  },
  "tokens": {
    "access_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
  }
}
```

***

## Login

```
POST https://api.predexy.com/api/v1/auth/login
```

Authenticates an existing developer account and returns fresh tokens.

### Request body

<ParamField body="email" type="string" required>
  Developer email address.
</ParamField>

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

### Example request

```bash cURL theme={null}
curl -X POST https://api.predexy.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@company.com",
    "password": "securepassword"
  }'
```

***

## Logout

```
POST https://api.predexy.com/api/v1/auth/logout
```

Clears the `pdx_access` and `pdx_refresh` httpOnly cookies. No request body required.

***

## Refresh tokens

```
POST https://api.predexy.com/api/v1/auth/refresh
```

Exchanges a valid refresh token for a new access token and refresh token pair. The refresh token is read from the `pdx_refresh` cookie or the `Authorization` header. Use this before the access token expires to maintain a continuous session.

***

## Get user profile

```
GET https://api.predexy.com/api/v1/auth/me
```

Returns the profile of the currently authenticated user. Requires a valid access token.

```bash cURL theme={null}
curl https://api.predexy.com/api/v1/auth/me \
  -H "Authorization: Bearer <your_access_token>"
```

***

## Password reset flow

Use these three endpoints in sequence to reset a forgotten password:

<Steps>
  <Step title="Request OTP">
    `POST /api/v1/auth/forgot-password` with `{"email": "dev@company.com"}`. A 6-digit OTP is sent to the registered email. The OTP expires in 10 minutes. This endpoint returns success even if the email is not registered, to prevent account enumeration.
  </Step>

  <Step title="Verify OTP">
    `POST /api/v1/auth/verify-otp` with `{"email": "dev@company.com", "otp": "482910"}`. On success, returns a short-lived `reset_token` valid for 5 minutes.
  </Step>

  <Step title="Set new password">
    `POST /api/v1/auth/reset-password` with `{"reset_token": "<token>", "password": "newpassword"}`. The token is single-use and consumed on success.
  </Step>
</Steps>

***

## Change password

```
POST https://api.predexy.com/api/v1/auth/change-password
```

Changes the password for an already-authenticated user. Requires a valid session.

### Request body

<ParamField body="current_password" type="string" required>
  The current account password.
</ParamField>

<ParamField body="new_password" type="string" required>
  The new password. Minimum 8 characters.
</ParamField>