Yoyo Authorisation Documentation

Doc type: Explanation

Yoyo Authorisation is the hosted authentication portal for auth.yoyogroup.com. It establishes a shared session across Yoyo subdomains by setting HttpOnly cookies scoped to .yoyogroup.com, then redirects users back to your app.

Supported integration options

Use Yoyo Authorisation in one of these supported ways:

• Hosted auth redirects + shared cookies: Redirect users to the hosted auth portal (/?redirectUrl=...), then read the shared HttpOnly cookies on *.yoyogroup.com from server-side code.
• OAuth 2.0 Authorization Code + PKCE: Use the OAuth2 endpoints (/api/oauth/authorize and /api/oauth/token) as a public client with a registered client_id and exact redirect_uri matches.
• Launch Pad: Add your app to the hosted Launch Pad so authenticated users can navigate to it from /launch.

Complete Integration Reference

For AI agents and comprehensive integration information, see the complete integration reference. This single file contains all environments, URLs, methods, supported features, constraints, OAuth flows, and cookie sharing mechanisms in one place.

Environments and hosts

Production

• Hosted auth: https://auth.yoyogroup.com
• Cookie prefix: yoyo_auth_

Integration

• Hosted auth: https://auth-int.yoyogroup.com
• Cookie prefix: yoyo_auth_int_

Choose your path

• Understand OAuth 2.0 support: See OAuth 2.0 Authentication.
• Redirect safely: See Handle Redirects And Allowlists.
• Add your app to Launch Pad: See Add Your App To Launch Pad.
• Consume the session: See Work With Shared Cookies and Build A BFF/Proxy.
• Internal allowlisting: See Whitelist Your Application (Coming Soon).

If you are just getting started, use the quickstarts:

• SSR Quickstart Next.js
• SPA Quickstart React Vite
• Mobile Quickstart Webview Or Browser
• Local Development Quickstart

For an end-to-end sample implementation, see the example apps in this repo:

• examples/yoyo-auth-nextjs-example - Next.js integration example with cookie-based and token-based sessions
• examples/yoyo-auth-spa-example - React + Vite SPA example demonstrating OAuth2 PKCE flow

What this documentation covers

• Hosted auth portal behavior, redirects, and the Launch Pad experience.
• Shared cookie contract and how to read sessions server-side.
• Public auth portal endpoints and integration surface area.
• Troubleshooting for hosted auth integrations.

Contact us

Email support.sa@yoyogroup.com for access requests, allowlist updates, or help with Launch Pad registration.

How authentication works at a glance

Yoyo Auth uses a standard OAuth2 authorization code flow with credentialed OAuth providers (Google). The flow works as follows:

1. Your app redirects the user to the hosted auth portal with a redirectUrl back to your app.
2. The portal authenticates the user via credentialed OAuth (Google) and sets HttpOnly cookies on .yoyogroup.com.
3. Your app reads the cookies server-side and forwards the access token to downstream APIs.

For Next.js applications, you have two options:

• Cookie-based session: Validate the shared cookies in middleware (recommended for apps on *.yoyogroup.com subdomains)
• Token-based session: Use the OAuth flow to exchange tokens and set your own session (useful for external apps or custom session management)

If you need the details behind each step, see Hosted Auth Overview and Work With Shared Cookies.