Store Gmail tokens

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

POST /v1/auth/gmail/store-tokens

cURL

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": "[e-mail]"
  }'

201

{
  "message": "Gmail OAuth tokens stored successfully!",
  "code": 201,
  "data": {
    "google_email": "[e-mail]",
    "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."
  }
}

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.

Authentication

Authorization · string · required

Bearer JWT token obtained from Login or Sign up. Format: Bearer <access_token>.

Request body

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

access_token · string · required

The Google OAuth 2.0 access token returned after Google Sign-In.

refresh_token · string

The Google OAuth 2.0 refresh token. Required to renew access when the access token expires.

expires_in · number · default: "3600"

Lifetime of the access token in seconds.

scope · 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.

email · string

The Google account email address associated with the tokens.

Response

message · string

A human-readable confirmation message. Example: "Gmail OAuth tokens stored successfully!"

code · number

HTTP status code. 201 on success.

data · object

Hide properties

google_email · string

The Google account email address retrieved from the access token via the Google userinfo API.

scope · string

Space-separated string of granted OAuth scopes.

account_switch · boolean

true if the user has connected a different Google account than the one previously stored.

message · string

A message describing the account consistency check result.

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:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid OAuth tokens"
  }
}

cURL

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": "[e-mail]"
  }'

201

{
  "message": "Gmail OAuth tokens stored successfully!",
  "code": 201,
  "data": {
    "google_email": "[e-mail]",
    "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."
  }
}