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

# Store Gmail tokens

> Store OAuth 2.0 tokens to connect a Gmail account to PayPulse.

<Note>
  This endpoint is called from the iOS app immediately after a successful Google Sign-In flow. The OAuth tokens obtained from Google are forwarded here to be securely stored in AWS Secrets Manager, enabling PayPulse to read Gmail invoices on the user's behalf.
</Note>

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer JWT token obtained from [Login](/api-reference/auth/login) or [Sign up](/api-reference/auth/signup). Format: `Bearer <access_token>`.
</ParamField>

## Request body

Accepts `application/json` or `application/x-www-form-urlencoded`.

<ParamField body="access_token" type="string" required>
  The Google OAuth 2.0 access token returned after Google Sign-In.
</ParamField>

<ParamField body="refresh_token" type="string">
  The Google OAuth 2.0 refresh token. Required to renew access when the access token expires.
</ParamField>

<ParamField body="expires_in" type="number" default="3600">
  Lifetime of the access token in seconds.
</ParamField>

<ParamField body="scope" type="string[]">
  Array of OAuth scope strings granted by the user (e.g. `["https://www.googleapis.com/auth/gmail.readonly"]`). When sending `application/x-www-form-urlencoded`, provide a comma-separated string.
</ParamField>

<ParamField body="email" type="string">
  The Google account email address associated with the tokens.
</ParamField>

## Response

<ResponseField name="message" type="string">
  A human-readable confirmation message. Example: `"Gmail OAuth tokens stored successfully!"`
</ResponseField>

<ResponseField name="code" type="number">
  HTTP status code. `201` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties" defaultOpen>
    <ResponseField name="google_email" type="string">
      The Google account email address retrieved from the access token via the Google userinfo API.
    </ResponseField>

    <ResponseField name="scope" type="string">
      Space-separated string of granted OAuth scopes.
    </ResponseField>

    <ResponseField name="account_switch" type="boolean">
      `true` if the user has connected a different Google account than the one previously stored.
    </ResponseField>

    <ResponseField name="message" type="string">
      A message describing the account consistency check result.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Error code              | Description                                                                            |
| ------ | ----------------------- | -------------------------------------------------------------------------------------- |
| `400`  | `INVALID_CREDENTIALS`   | The OAuth tokens failed validation (e.g. missing required scopes or token is invalid). |
| `400`  | `INVALID_JSON`          | The request body is not valid JSON.                                                    |
| `400`  | `MISSING_FIELDS`        | A required field is absent from the request body.                                      |
| `502`  | `DEPENDENCY_FAILURE`    | Failed to communicate with Google APIs or AWS Secrets Manager.                         |
| `500`  | `INTERNAL_SERVER_ERROR` | An unexpected server-side error occurred.                                              |

Error responses follow this structure:

```json theme={null}
{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid OAuth tokens"
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.paypulse.io/v1/auth/gmail/store-tokens \
    --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
    --header 'Content-Type: application/json' \
    --data '{
      "access_token": "ya29.a0AfH6SMB...",
      "refresh_token": "1//0eXx...",
      "expires_in": 3599,
      "scope": [
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      "email": "jane@gmail.com"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "message": "Gmail OAuth tokens stored successfully!",
    "code": 201,
    "data": {
      "google_email": "jane@gmail.com",
      "scope": "https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/userinfo.email",
      "account_switch": false,
      "message": "Google account is consistent with previously stored account."
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "INVALID_CREDENTIALS",
      "message": "Invalid OAuth tokens"
    }
  }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": "DEPENDENCY_FAILURE",
      "message": "Network error communicating with Google"
    }
  }
  ```
</ResponseExample>