Social sign-in
Let users sign in with Google, Apple, or GitHub.
Social sign-in
Ploy Auth supports Google, Apple, and GitHub. You bring your own OAuth credentials, so the consent screen shows your app's name and users' accounts belong to you.
Set up a provider
-
Create OAuth credentials with the provider (below).
-
Register the callback URL for every domain users sign in from:
https://<your-domain>/_ploy/auth/callback/<provider>The dashboard shows it for your project's production URL. Add the same path for each custom domain and any preview URL you want to sign in on.
-
In the dashboard, open Auth → Settings, enter the credentials under the provider, turn it on, and click Save settings.
The provider appears in GET /_ploy/auth/config and in the SignInForm and SignUpForm components right away.
- In Google Cloud Console, open APIs & Services → Credentials and create an OAuth client ID of type Web application.
- Add the callback URL under Authorized redirect URIs.
- Copy the Client ID and Client secret into Ploy.
Ploy requests the openid email profile scopes and uses PKCE. To call Google APIs, add their scopes under Additional scopes and enable the APIs in Google Cloud Console.
GitHub
- In GitHub, open Settings → Developer settings → OAuth Apps → New OAuth App.
- Set Authorization callback URL to the callback URL.
- Generate a client secret and copy the Client ID and secret into Ploy.
Ploy requests read:user user:email and uses the account's primary verified email. GitHub accounts without a verified email cannot sign in. To call the GitHub API with more access, such as repo, add the scopes under Additional scopes.
Apple
Sign in with Apple needs a paid Apple Developer account.
- Under Certificates, Identifiers & Profiles, create an App ID with Sign in with Apple enabled.
- Create a Services ID, enable Sign in with Apple, and add your domain and the callback URL as a return URL. Apple requires HTTPS.
- Under Keys, create a key with Sign in with Apple enabled and download the
.p8file. - In Ploy, enter:
| Field | Value |
|---|---|
| Services ID | The Services ID identifier, e.g. com.example.web |
| Team ID | Your 10-character Apple Developer team ID |
| Key ID | The key's 10-character ID |
| Private key (.p8) | The full contents of the .p8 file |
Ploy signs a short-lived client secret with the key on every sign-in, so there is nothing to rotate every six months. Apple sends the user's name only on their first sign-in; Ploy stores it in metadata.name when it creates the account. Users who choose Hide My Email get a private relay address.
The private key and client secrets are encrypted at rest and never returned by the API. To rotate one, paste the new value and save.
Start sign-in
With @meetploy/auth-react, enabled providers show up in SignInForm and SignUpForm automatically, or call signInWithProvider:
const { signInWithProvider } = useAuth();
<button
onClick={() => signInWithProvider("github", { redirectTo: "/dashboard" })}
>
Continue with GitHub
</button>;Without React, navigate to the endpoint:
window.location.href =
"/_ploy/auth/oauth/github?redirectTo=" + encodeURIComponent("/dashboard");Request additional scopes
By default Ploy only asks for the scopes it needs to read the user's identity. To call a provider's API for the user, add scopes in the dashboard: open Auth → Settings, enter them under the provider in Additional scopes, separated by spaces, and click Save settings.
| Provider | Always requested | Example additional scopes |
|---|---|---|
| GitHub | read:user user:email | repo for private repositories, read:org for organization membership |
openid email profile | https://www.googleapis.com/auth/calendar.readonly | |
| Apple | name email | Apple offers no other scopes |
Only organization owners and admins can change provider settings. Google and GitHub each accept up to 50 additional scope tokens, each at most 256 characters; whitespace, commas, quotes and backslashes cannot appear inside a token. Separate tokens with spaces in the dashboard. The identity scopes are always requested, and duplicates are removed.
When you change the scopes, users who already signed in keep their current token until they sign in with the provider again; the provider then asks them to approve the new scopes. Until then, getProviderToken lists the scopes they have not approved in missingScopes.
For Google, Ploy requests offline access and a fresh consent screen while additional scopes are set. This lets an existing grant issue a new refresh token too, including when a previously stored refresh token expired or was revoked. Google may require verification for sensitive or restricted scopes.
Removing a configured scope does not revoke tokens or permissions already granted at the provider. Revoke the grant in the provider's account settings if access must be removed.
Call the provider API
When a user signs in with a provider, Ploy stores the provider's access token, refresh token, expiry, and granted scopes on the identity. On deployments, access and refresh tokens are encrypted with a key derived from the auth binding's signing secret, held by the platform rather than your worker or auth database. Ciphertexts are bound to the identity and token column. Direct database reads return ciphertext, not usable tokens.
The key stays stable across redeploys and OAuth credential changes. Replacing the auth binding or its signing secret makes existing encrypted tokens unreadable; users must sign in again. Your server code and anyone with write access to the auth database remain trusted: encryption is not a substitute for restricting database access.
Read the signed-in user's token in server code. With Next.js:
import { getProviderToken } from "@meetploy/nextjs/auth";
export async function GET() {
const github = await getProviderToken("github");
if (!github || github.missingScopes.length > 0) {
return Response.json(
{ connect: "/_ploy/auth/oauth/github?redirectTo=/repos" },
{ status: 403 },
);
}
const response = await fetch("https://api.github.com/user/repos", {
headers: {
Authorization: `Bearer ${github.accessToken}`,
Accept: "application/vnd.github+json",
"User-Agent": "my-app",
},
});
return Response.json(await response.json());
}In any worker, pass the session token to the PLOY_AUTH binding:
const github = await env.PLOY_AUTH.getProviderToken(sessionToken, "github");| Field | Value |
|---|---|
provider | google, apple or github |
accessToken | Send it as Authorization: Bearer <accessToken> to the provider's API |
expiresAt | ISO 8601 expiry, or null when the token does not expire |
scopes | The scopes the user granted |
missingScopes | Additional scopes you configured that the user has not approved yet |
When the access token expires within a minute, Ploy refreshes it first if the provider issued a refresh token: Google with additional scopes, Apple, and GitHub Apps with expiring user tokens. GitHub OAuth App tokens have no scheduled expiry but can still be revoked. The refresh token itself is never returned. Concurrent refreshes are serialized through a short database lease, including across replicas; an older refresh cannot replace tokens from a newer sign-in.
missingScopes compares configured scope names with the returned grant list. Providers can normalize scope names or return broader scopes; check provider documentation when interpreting the list. Network errors and temporary refresh contention throw instead of returning null; retry these failures rather than forcing the user to reconnect.
getProviderToken returns null when the session is invalid, when the user has no stored token for the provider, or when the token expired and cannot be refreshed. Users who signed in before tokens were stored also get null. In each case, send the user to /_ploy/auth/oauth/<provider>?redirectTo=<path>: a signed-in user is linked again, and Ploy stores the new token and scopes.
Provider tokens are for server code only. They are available through the
PLOY_AUTH binding and never through /_ploy/auth/* from the browser. Keep
them on the server and call the provider from there. Unlinking an identity
deletes its tokens; to revoke the grant itself, the user removes your app in
the provider's account settings.
Errors
When sign-in does not complete, the user is sent back to redirectTo with a ploy_auth_error parameter. useAuth().redirectError exposes it and removes it from the URL.
| Code | Meaning |
|---|---|
access_denied | The user cancelled at the provider |
account_exists | An account with this email exists and the provider did not verify the email |
email_required | The provider did not share a verified email address |
signups_disabled | No account exists for this identity and sign-ups are off |
plus_address_not_allowed | No account exists and the provider's email has a + tag the project refuses |
email_domain_blocked | No account exists and the provider's email is on a blocked disposable or forwarding domain |
invalid_state | The sign-in attempt expired (after 10 minutes) or was tampered with |
provider_disabled | The provider was turned off during sign-in |
rate_limited | Too many attempts from this IP |
oauth_failed | The provider rejected the code exchange |
Account linking
Ploy keeps one user per email address and links provider identities to it:
- A returning identity (same provider and provider user ID) signs in to the user it is linked to, even if the email at the provider changed.
- If the user is already signed in, the new identity is linked to their account.
- If the provider reports a verified email that matches an existing user, the identity is linked to that user.
- Otherwise a new user is created, if sign-ups are allowed.
A provider email that is not verified is never linked to an existing account.
Takeover protection. Ploy does not verify emails for password and passkey sign-ups, so anyone could register an address they don't own. When a verified provider identity links to such an unverified account, Ploy first removes its password and passkeys and revokes its sessions, then marks the email verified. The owner of the email keeps the account; whoever registered it without owning it loses access.
Lifecycle hooks
Before hooks can reject a new social account (beforeSignUp) or a new session (beforeSignIn). A refused OAuth callback redirects with ploy_auth_error=signup_blocked, signin_blocked, or hook_failed; refusal text is not copied into the redirect URL. Social profile data and metadata are not authorization policy.
Local development
ploy dev reads provider credentials from your project's .env. A provider is enabled when all its variables are set:
PLOY_AUTH_GOOGLE_CLIENT_ID=...
PLOY_AUTH_GOOGLE_CLIENT_SECRET=...
PLOY_AUTH_GITHUB_CLIENT_ID=...
PLOY_AUTH_GITHUB_CLIENT_SECRET=...
PLOY_AUTH_APPLE_CLIENT_ID=...
PLOY_AUTH_APPLE_TEAM_ID=...
PLOY_AUTH_APPLE_KEY_ID=...
PLOY_AUTH_APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"Set additional scopes with PLOY_AUTH_GITHUB_SCOPES and PLOY_AUTH_GOOGLE_SCOPES, separated by spaces, e.g. PLOY_AUTH_GITHUB_SCOPES="repo read:org". These are development environment settings, not ploy.yaml fields; deployed credentials and scopes are managed in the dashboard. getProviderToken works locally through the same server helpers.
The local emulator uses a built-in development signing secret, not the platform-held production key. Do not treat local token ciphertext as protected from someone who can read the emulator database; use test accounts and keep local data private.
Register http://localhost:<port>/_ploy/auth/callback/<provider> with the provider, where <port> is your dev server's port. Google and GitHub accept localhost callbacks; Apple only accepts HTTPS, so test Apple on a deployment.
How is this guide?
Last updated on