Authenticating External Apps or Widgets via ScaleGrowth using OAuth 2.0

This guide explains how to authenticate users of external applications or widgets (e.g., embedded tools or microsites) using ScaleGrowth's OAuth 2.0-compatible API.

Please refer to the comprehensive OAuth 2.0 Simplified guide for a detailed walk-through of the supported authentication flows and protocols.

When to Use This

Use this guide if you are:

• Building an external widget or microservice that needs to authenticate users with ScaleGrowth credentials.
• Implementing secure access control to ensure only authenticated users can interact with your service.

ScaleGrowth supports standard OAuth 2.0 flows and is compatible with any standards-based OAuth 2.0 client library.

OAuth 2.0 Endpoints on ScaleGrowth

• Authorization Endpoint: /o/authorize/
• Token Endpoint: /o/token/
• User Info Endpoint: /o/userinfo/
• Revoke Token: /o/revoke_token/

All endpoints should be accessed via your white-labeled domain (e.g., https://app.yourdomain.com/o/authorize/).

Option 1: Authorization Code Flow (Recommended for Web Apps)

Use when:

• Your widget or external app has a secure backend server
• You want long-lived sessions and refresh tokens

Flow Summary:

1. User clicks "Login" in your widget
2. Redirect to /o/authorize/ with your app’s client_id and desired scopes
3. User logs in via ScaleGrowth and authorizes
4. ScaleGrowth redirects back to your redirect URI with code
5. Your server exchanges the code at /o/token/ for an access_token (and optionally a refresh_token)
6. Use /o/userinfo/ with the access token to retrieve authenticated user details

Resources:

• OAuth 2.0 Authorization Code Flow

Option 2: Resource Owner Password Credentials Grant (for Internal Apps Only)

Use when:

• You control both the front end and backend
• You want to allow users to enter their username/password directly into your widget (less secure)

⚠️ Note: This flow is discouraged in most OAuth 2.0 setups and should only be used in trusted internal tools.

Flow Summary:

1. Your frontend widget collects username and password
2. Send them to /o/token/ with grant_type=password, username, and password
3. Receive access token and use it to call /o/userinfo/

Resources:

• Password Grant Overview

Option 3: Client Credentials Flow (Service-to-Service Authentication)

Use when:

• The widget or tool doesn’t act on behalf of an individual user
• You just need system-to-system access using your app’s client credentials

Flow Summary:

1. Your backend requests an access token from /o/token/ using grant_type=client_credentials
2. You receive a token and can use it to access protected endpoints (if your client has permission)

Resources:

• Client Credentials Grant

Example: Adding OAuth to an AWS Lambda Widget

1. Add a login button to your widget that redirects users to /o/authorize/
2. In your backend (e.g., AWS Lambda + API Gateway), create a route to handle the callback from ScaleGrowth and exchange the code for a token
3. Store the access token in a secure session or token store
4. Use the access token to call /o/userinfo/ to retrieve user identity
5. Use this info to render your widget or gate access

Notes and Best Practices

• Always use HTTPS for token exchanges and callback URLs
• Store refresh tokens securely if using long-lived sessions
• Avoid embedding client secrets in frontend code
• Use short-lived access tokens and refresh them when needed
• Scope access as narrowly as possible

Summary

ScaleGrowth supports OAuth 2.0 for secure user authentication from external widgets or applications. Depending on your architecture, you can choose the Authorization Code flow for web-based widgets, or other flows for trusted internal tools. Follow OAuth best practices and use /o/authorize/ and /o/token/ to securely authenticate and retrieve user information.

We are here to support you in your integrations. If you have a specific use-case, please reach out via Ask SG Team in your Success Center outlining it – and our customer success team is happy to help!