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

# Authentication

> Authenticate users and manage auth sessions

The Authentication API allows you to authenticate users via multiple methods including password, OAuth2, and one-time passwords (OTP).

## Get auth methods

Retrieve available authentication methods for a collection.

```bash theme={null}
GET /api/collections/{collection}/auth-methods
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Response

<ResponseField name="password" type="object">
  Password authentication configuration

  <Expandable>
    <ResponseField name="enabled" type="boolean">
      Whether password authentication is enabled
    </ResponseField>

    <ResponseField name="identityFields" type="array">
      Fields that can be used as identity (e.g., `["email", "username"]`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="oauth2" type="object">
  OAuth2 authentication configuration

  <Expandable>
    <ResponseField name="enabled" type="boolean">
      Whether OAuth2 is enabled
    </ResponseField>

    <ResponseField name="providers" type="array">
      Available OAuth2 providers with auth URLs and PKCE parameters
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="otp" type="object">
  One-time password configuration

  <Expandable>
    <ResponseField name="enabled" type="boolean">
      Whether OTP authentication is enabled
    </ResponseField>

    <ResponseField name="duration" type="number">
      OTP validity duration in seconds
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="mfa" type="object">
  Multi-factor authentication configuration

  <Expandable>
    <ResponseField name="enabled" type="boolean">
      Whether MFA is enabled
    </ResponseField>

    <ResponseField name="duration" type="number">
      MFA session duration in seconds
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl http://127.0.0.1:8090/api/collections/users/auth-methods
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://127.0.0.1:8090/api/collections/users/auth-methods');
  const methods = await response.json();
  ```
</CodeGroup>

## Authenticate with password

Authenticate a user with identity and password.

```bash theme={null}
POST /api/collections/{collection}/auth-with-password
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="identity" type="string" required>
  The user's identity (email, username, or other configured field)
</ParamField>

<ParamField body="password" type="string" required>
  The user's password
</ParamField>

<ParamField body="identityField" type="string">
  Specific field to use for identity lookup (leave empty for auto-detection)
</ParamField>

### Response

<ResponseField name="token" type="string">
  JWT authentication token
</ResponseField>

<ResponseField name="record" type="object">
  The authenticated user record
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/auth-with-password \
    -H "Content-Type: application/json" \
    -d '{
      "identity": "user@example.com",
      "password": "your_password"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://127.0.0.1:8090/api/collections/users/auth-with-password', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      identity: 'user@example.com',
      password: 'your_password'
    })
  });
  const data = await response.json();
  ```
</CodeGroup>

## Authenticate with OAuth2

Authenticate a user via OAuth2 provider.

```bash theme={null}
POST /api/collections/{collection}/auth-with-oauth2
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="provider" type="string" required>
  OAuth2 provider name (e.g., `google`, `github`, `facebook`)
</ParamField>

<ParamField body="code" type="string" required>
  Authorization code from the OAuth2 provider
</ParamField>

<ParamField body="redirectURL" type="string" required>
  The redirect URL used in the initial OAuth2 request
</ParamField>

<ParamField body="codeVerifier" type="string">
  PKCE code verifier (required if provider uses PKCE)
</ParamField>

<ParamField body="createData" type="object">
  Additional data for creating a new user if one doesn't exist
</ParamField>

### Response

<ResponseField name="token" type="string">
  JWT authentication token
</ResponseField>

<ResponseField name="record" type="object">
  The authenticated user record
</ResponseField>

<ResponseField name="meta" type="object">
  OAuth2 user data and `isNew` flag
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/auth-with-oauth2 \
    -H "Content-Type: application/json" \
    -d '{
      "provider": "google",
      "code": "authorization_code",
      "redirectURL": "http://localhost:3000/auth/callback",
      "codeVerifier": "pkce_verifier"
    }'
  ```
</CodeGroup>

## Authenticate with OTP

Authenticate using a one-time password.

```bash theme={null}
POST /api/collections/{collection}/auth-with-otp
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="otpId" type="string" required>
  The OTP record ID
</ParamField>

<ParamField body="password" type="string" required>
  The OTP password/code
</ParamField>

### Response

<ResponseField name="token" type="string">
  JWT authentication token
</ResponseField>

<ResponseField name="record" type="object">
  The authenticated user record
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/auth-with-otp \
    -H "Content-Type: application/json" \
    -d '{
      "otpId": "otp_record_id",
      "password": "123456"
    }'
  ```
</CodeGroup>

## Request OTP

Request a new one-time password to be sent to the user.

```bash theme={null}
POST /api/collections/{collection}/request-otp
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="email" type="string" required>
  The user's email address
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/request-otp \
    -H "Content-Type: application/json" \
    -d '{"email": "user@example.com"}'
  ```
</CodeGroup>

## Refresh authentication

Refresh an existing auth token.

```bash theme={null}
POST /api/collections/{collection}/auth-refresh
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

**Authentication required:** Yes (must be authenticated with the same collection)

### Response

<ResponseField name="token" type="string">
  New JWT authentication token
</ResponseField>

<ResponseField name="record" type="object">
  The authenticated user record
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/auth-refresh \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

## Request password reset

Request a password reset email.

```bash theme={null}
POST /api/collections/{collection}/request-password-reset
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="email" type="string" required>
  The user's email address
</ParamField>

### Response

Returns 204 No Content on success (even if email doesn't exist, to prevent enumeration).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/request-password-reset \
    -H "Content-Type: application/json" \
    -d '{"email": "user@example.com"}'
  ```
</CodeGroup>

## Confirm password reset

Confirm password reset with token.

```bash theme={null}
POST /api/collections/{collection}/confirm-password-reset
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="token" type="string" required>
  The password reset token from the email
</ParamField>

<ParamField body="password" type="string" required>
  The new password
</ParamField>

<ParamField body="passwordConfirm" type="string" required>
  Password confirmation (must match password)
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-password-reset \
    -H "Content-Type: application/json" \
    -d '{
      "token": "reset_token_from_email",
      "password": "new_password",
      "passwordConfirm": "new_password"
    }'
  ```
</CodeGroup>

## Request verification

Request an email verification message.

```bash theme={null}
POST /api/collections/{collection}/request-verification
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="email" type="string" required>
  The user's email address to verify
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/request-verification \
    -H "Content-Type: application/json" \
    -d '{"email": "user@example.com"}'
  ```
</CodeGroup>

## Confirm verification

Confirm email verification.

```bash theme={null}
POST /api/collections/{collection}/confirm-verification
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="token" type="string" required>
  The verification token from the email
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-verification \
    -H "Content-Type: application/json" \
    -d '{"token": "verification_token_from_email"}'
  ```
</CodeGroup>

## Request email change

Request to change the authenticated user's email.

```bash theme={null}
POST /api/collections/{collection}/request-email-change
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

**Authentication required:** Yes

### Request body

<ParamField body="newEmail" type="string" required>
  The new email address
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/request-email-change \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"newEmail": "newemail@example.com"}'
  ```
</CodeGroup>

## Confirm email change

Confirm email change with token.

```bash theme={null}
POST /api/collections/{collection}/confirm-email-change
```

<ParamField path="collection" type="string" required>
  The name or ID of the auth collection
</ParamField>

### Request body

<ParamField body="token" type="string" required>
  The email change token
</ParamField>

<ParamField body="password" type="string" required>
  The user's current password
</ParamField>

### Response

Returns 204 No Content on success.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-email-change \
    -H "Content-Type: application/json" \
    -d '{
      "token": "email_change_token",
      "password": "current_password"
    }'
  ```
</CodeGroup>

## Common error codes

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 400  | Invalid credentials or validation error          |
| 403  | Authentication method not enabled for collection |
| 404  | Collection not found or not an auth collection   |
| 429  | Too many authentication attempts                 |