Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fredy-rizo/Ecommerce/llms.txt

Use this file to discover all available pages before exploring further.

The Ecommerce API integrates Google OAuth 2.0 via Passport.js, allowing users to sign in with their existing Google account instead of creating a separate password. The API automatically creates a new user document the first time a Google account is seen, assigns the standard Usuario role, and issues a 365-day JWT — the same token format used by the native JWT flow.
Google OAuth uses a browser-based redirect flow. The user’s browser is redirected to Google’s consent screen and then back to the API callback URL. This flow is not suitable for direct API calls (e.g., from a mobile app using raw HTTP requests or from server-to-server integrations). For those use cases, use the native JWT authentication flow instead.

​
Prerequisites

Before the OAuth flow will work, three environment variables must be set on the API server:
VariableDescription
CLIENT_IDThe OAuth 2.0 client ID from your Google Cloud Console project
CLIENT_SECRETThe client secret paired with the client ID
CLIENT_URLThe callback URL registered in Google Cloud Console (e.g. https://your-api-domain.com/auth/google/callback)
CLIENT_URL must exactly match one of the Authorized redirect URIs configured in your Google Cloud Console OAuth 2.0 credentials. A mismatch will cause Google to reject the callback with a redirect_uri_mismatch error.

​
Setting up Google OAuth credentials

1

Create or select a Google Cloud project

Go to the Google Cloud Console and either create a new project or select an existing one from the project picker in the top navigation bar.
2

Enable the Google People API

Navigate to APIs & Services → Library and search for Google People API. Click Enable to allow your project to request profile and email scopes.
3

Configure the OAuth consent screen

Go to APIs & Services → OAuth consent screen. Choose External if your app is for general users.Fill in the required fields:
  • App name — shown to users on the consent screen
  • User support email — a contact email for OAuth-related queries
  • Authorized domains — add your API’s root domain (e.g. your-api-domain.com)
  • Developer contact information
Under Scopes, add the email and profile scopes, which correspond to the scopes requested by the Passport.js strategy.
4

Create OAuth 2.0 credentials

Go to APIs & Services → Credentials and click Create Credentials → OAuth client ID.
  • Application type: Web application
  • Name: A descriptive label (e.g. Ecommerce API OAuth Client)
  • Authorized JavaScript origins: Your API’s origin (e.g. https://your-api-domain.com)
  • Authorized redirect URIs: The exact value you will use for CLIENT_URL (e.g. https://your-api-domain.com/auth/google/callback)
Click Create. Copy the Client ID and Client Secret and set them as CLIENT_ID and CLIENT_SECRET in your API’s environment.
5

Set environment variables

Add the credentials to your API server’s environment. For a local .env file:
.env
CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com
CLIENT_SECRET=GOCSPX-your-client-secret-here
CLIENT_URL=https://your-api-domain.com/auth/google/callback
Never commit your .env file to version control. Use your hosting platform’s secret management (e.g. environment variables in Railway, Render, or AWS) for production deployments.

​
OAuth authentication flow

Once credentials are configured, the full sign-in flow works as follows:
1

User navigates to GET /auth/google

The client (typically a login button in the browser) sends the user to:
GET /auth/google
The Passport.js middleware intercepts this request and builds a Google authorization URL with the requested scopes.
The API requests the email and profile scopes, so Google will ask the user to share their name, profile picture, and email address.
2

User sees the Google consent screen

The browser is redirected to Google’s OAuth consent screen. The user selects their Google account and grants the requested permissions. Google then generates an authorization code and prepares to redirect back to the API.
3

Google redirects to GET /auth/google/callback

Google calls back to the URL configured in CLIENT_URL (e.g. /auth/google/callback), appending an authorization code as a query parameter. Passport.js automatically exchanges this code for tokens and fetches the user’s Google profile.
GET /auth/google/callback?code=4/0AfJohXn...&scope=email+profile
This route is handled entirely by the API — the client does not need to send any additional data.
4

API finds or creates the user by googleId

The Passport.js strategy callback receives the Google profile object and searches the database for an existing user document with a matching googleId.
  • Existing user: The user document is retrieved, a new 365-day JWT is signed and saved to the User document, and the user is passed to the session.
  • New user: A new user document is created using the profile data (googleId, userName from profile.displayName, and email from profile.emails[0].value).
The strategy callback in src/middleware/utils/passport.js uses the signature (profile, done) — two parameters. The profile object is the Google profile returned after Passport has already exchanged the authorization code internally.
Because Google verifies the user’s email as part of the OAuth flow, new accounts created through Google sign-in are immediately active — no email verification step is required.
5

New Google users are assigned default role and active status

All users created through the Google OAuth flow are automatically assigned:
FieldValue
roles[{ name: "Usuario", value: "1" }]
activate[{ name: "Activado", value: "1" }]
This mirrors the state of a native user who has completed email verification. Admin roles must be assigned manually in the database after account creation.
6

A 365-day JWT is issued and stored

The API signs a JWT using config.SECRET with a 365d expiry. The token is stored on the User document.
7

Browser is redirected to /protected

On a successful callback, the API redirects the browser to /protected. On failure (e.g. the user denies consent or an error occurs), the browser is redirected to /auth/failure.
HTTP/1.1 302 Found
Location: /protected
Once you have the token, store it securely (e.g. in localStorage or an httpOnly cookie) and attach it to all protected API requests using the token-access header — exactly as described in the JWT authentication guide.

​
Using the token after OAuth sign-in

After a successful Google OAuth sign-in, the resulting JWT is used exactly like a token obtained from POST /api/user/login. Attach it to the token-access header on every call to a protected endpoint:
cURL
curl -X GET https://your-api-domain.com/api/products \
  -H "token-access: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
See the JWT authentication guide for the full list of token payload fields, error responses, and role-based access details.

​
Passport.js strategy configuration reference

The Google strategy is configured in src/middleware/utils/passport.js using the following environment variables:

CLIENT_ID

The OAuth 2.0 client ID from Google Cloud Console. Identifies your application to Google.

CLIENT_SECRET

The client secret paired with CLIENT_ID. Keep this value private and never expose it in client-side code.

CLIENT_URL

The authorized redirect URI. Must exactly match the value registered in Google Cloud Console under your OAuth 2.0 credentials.

Build docs developers (and LLMs) love

Get started for freeTalk to us