Add social OAuth login to your EdgeSpark app

EdgeSpark ships with a managed auth service that handles OAuth flows end to end. To turn on a social provider such as Google or GitHub, you register an OAuth app with the provider, store the client ID as a var and the client secret as a secret, then enable the provider in configs/auth-config.yaml and deploy. The managed auth UI in @edgespark/web reads your applied config and renders the right buttons automatically — no frontend changes are needed when you add a new provider.

The shape of every provider setup

Every OAuth provider follows the same four-step pattern:

Create an OAuth app with the provider and enter the EdgeSpark callback URL.
Store the client ID as a var: edgespark var set <PROVIDER>_CLIENT_ID=<value>.
Store the client secret as a secret: edgespark secret set <PROVIDER>_CLIENT_SECRET.
Enable the provider in configs/auth-config.yaml, run edgespark auth apply, then edgespark deploy.

edgespark secret set opens a secure EdgeSpark browser URL for the human owner to paste the secret value. Secret values never pass through terminal output, agent context, or third-party LLM APIs such as Anthropic, Google, or OpenAI.

Callback URL

When you create the OAuth app with the provider, set the authorization callback (redirect) URL to:

https://<your-domain>/api/_es/auth/callback/<provider>

Where:

<your-domain> is your deployed project URL, for example my-app.edgespark.app, or your custom domain.
<provider> is one of: google, github, gitlab, discord.

Most providers let you register several callback URLs, so you can add both your EdgeSpark URL and any custom domain at the same time.

Fixed var and secret names

Key names are fixed per provider — you cannot choose arbitrary names. The platform reads the values through these exact keys.

Provider	YAML key	Client ID var	Client secret	Extra config
Google	`providerGoogle`	`GOOGLE_CLIENT_ID`	`GOOGLE_CLIENT_SECRET`	—
GitHub	`providerGithub`	`GITHUB_CLIENT_ID`	`GITHUB_CLIENT_SECRET`	—
GitLab	`providerGitlab`	`GITLAB_CLIENT_ID`	`GITLAB_CLIENT_SECRET`	—
Discord	`providerDiscord`	`DISCORD_CLIENT_ID`	`DISCORD_CLIENT_SECRET`	—

If your own server code also needs to read these values — for example, to call the provider’s API directly — declare the keys in server/src/defs/runtime.ts. That step is optional for the auth flow itself, which is fully handled by the platform.

Google

Open the Google Cloud Console and select or create a project.
Go to APIs & Services → Credentials and click Create credentials → OAuth client ID.
Configure the OAuth consent screen if prompted (External user type is typical for consumer apps).
Choose Web application as the application type and give it a name.
Under Authorized JavaScript origins, add your deployed project URL:
```
https://<your-domain>
```
For example, https://my-app.edgespark.app.

Under Authorized redirect URIs, add:

https://<your-domain>/api/_es/auth/callback/google

Copy the Client ID and Client secret from the credential details page.

Store them with the CLI:

edgespark var set GOOGLE_CLIENT_ID=<client-id>
edgespark secret set GOOGLE_CLIENT_SECRET

Enable the provider in configs/auth-config.yaml:

configs/auth-config.yaml

providerGoogle:
  enabled: true
  config:
    clientIdVarRef: GOOGLE_CLIENT_ID
    clientSecretRef: GOOGLE_CLIENT_SECRET

Apply and deploy:

edgespark auth apply
edgespark deploy

GitHub

Open GitHub Settings → Developer settings → OAuth Apps (either on your user account or organization) and click New OAuth App.
Set Homepage URL to your deployed project URL, for example https://my-app.edgespark.app.

Set Authorization callback URL to:

https://<your-domain>/api/_es/auth/callback/github

After creating the app, copy the Client ID and click Generate a new client secret. Copy the secret value immediately — GitHub shows it only once.

Store them with the CLI:

edgespark var set GITHUB_CLIENT_ID=<client-id>
edgespark secret set GITHUB_CLIENT_SECRET

Enable the provider in configs/auth-config.yaml:

configs/auth-config.yaml

providerGithub:
  enabled: true
  config:
    clientIdVarRef: GITHUB_CLIENT_ID
    clientSecretRef: GITHUB_CLIENT_SECRET

Apply and deploy:
```
edgespark auth apply
edgespark deploy
```

GitLab

In GitLab, open User Settings → Applications for a personal app, or Admin → Applications for an instance-wide app.

Give the application a name and add the Redirect URI:

https://<your-domain>/api/_es/auth/callback/gitlab

Select at least the read_user and openid scopes (plus email and profile if you want the user’s email and name).
Save the application, then copy the Application ID (this is the client ID) and Secret.

Store them with the CLI:

edgespark var set GITLAB_CLIENT_ID=<application-id>
edgespark secret set GITLAB_CLIENT_SECRET

Enable the provider in configs/auth-config.yaml:

configs/auth-config.yaml

providerGitlab:
  enabled: true
  config:
    clientIdVarRef: GITLAB_CLIENT_ID
    clientSecretRef: GITLAB_CLIENT_SECRET

Apply and deploy:
```
edgespark auth apply
edgespark deploy
```

Discord

Open the Discord Developer Portal and click New Application.
In the application, open OAuth2 → General.

Under Redirects, add:

https://<your-domain>/api/_es/auth/callback/discord

Copy the Client ID, then click Reset Secret to generate a Client Secret.

Store them with the CLI:

edgespark var set DISCORD_CLIENT_ID=<client-id>
edgespark secret set DISCORD_CLIENT_SECRET

Enable the provider in configs/auth-config.yaml:

configs/auth-config.yaml

providerDiscord:
  enabled: true
  config:
    clientIdVarRef: DISCORD_CLIENT_ID
    clientSecretRef: DISCORD_CLIENT_SECRET

Apply and deploy:
```
edgespark auth apply
edgespark deploy
```

Use enabled providers in the UI

The managed auth UI picks up every enabled provider automatically:

web/src/pages/LoginPage.tsx

import { useEffect, useRef } from "react";
import { client } from "@/lib/edgespark";

export function LoginPage() {
  const containerRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    const mounted = client.authUI.mount(containerRef.current, {
      redirectTo: "/dashboard",
    });

    return () => {
      mounted.destroy();
    };
  }, []);

  return <div ref={containerRef} />;
}

To trigger a provider from your own button instead of the managed UI, call client.auth.signIn.social:

web/src/lib/auth.ts

import { client } from "@/lib/edgespark";

export async function signInWithGitHub() {
  await client.auth.signIn.social({
    provider: "github",
    callbackURL: "/dashboard",
  });
}

provider accepts any of "google", "github", "gitlab", or "discord" — use the same string as in the callback URL.

Full example: enabling multiple providers

configs/auth-config.yaml

# yaml-language-server: $schema=https://schemas.edgespark.dev/v1/auth-config.schema.json

disableSignUp: false

providerEmailPassword:
  enabled: true
  config:
    minPasswordLength: 10
    requireEmailVerification: true

providerGoogle:
  enabled: true
  config:
    clientIdVarRef: GOOGLE_CLIENT_ID
    clientSecretRef: GOOGLE_CLIENT_SECRET

providerGithub:
  enabled: true
  config:
    clientIdVarRef: GITHUB_CLIENT_ID
    clientSecretRef: GITHUB_CLIENT_SECRET

providerDiscord:
  enabled: true
  config:
    clientIdVarRef: DISCORD_CLIENT_ID
    clientSecretRef: DISCORD_CLIENT_SECRET

Troubleshooting

Symptom	Likely cause	Fix
`edgespark auth apply` validation error on a provider config	A provider with `enabled: true` requires both `clientIdVarRef` and `clientSecretRef`.	Fill in both fields in `configs/auth-config.yaml`. An empty `config: {}` will fail validation.
Login button missing in the managed UI	Config not applied or not deployed.	Run `edgespark auth apply` then `edgespark deploy`. Verify with `edgespark auth get` that the provider has `enabled: true`.
`redirect_uri_mismatch` from the provider	The callback URL registered with the provider does not match the URL EdgeSpark sent.	Re-register `https://<your-domain>/api/_es/auth/callback/<provider>` exactly — `https`, exact host, lowercase provider name.
Provider returns `invalid_client`	Wrong, missing, or expired client ID or client secret.	Confirm `edgespark var list` shows the right `<PROVIDER>_CLIENT_ID` value and `edgespark secret list` shows `<PROVIDER>_CLIENT_SECRET`. Re-run `edgespark var set` or `edgespark secret set` if needed.
Validation mentions unknown or newer fields	CLI version is outdated for the schema.	Compare your YAML with `https://schemas.edgespark.dev/v1/auth-config.schema.json` and upgrade the CLI with `npm update -g @edgespark/cli`.

For platform-wide naming and quota limits, see platform limits.

Manage auth configuration

Full configs/auth-config.yaml reference, including sessions and email/password.

Build auth UI

Mount the managed auth UI or call headless auth methods from the browser.

Getting started

Concepts

Build

Deploy

Add social OAuth login to your EdgeSpark app

The shape of every provider setup

Callback URL

Fixed var and secret names

Google

GitHub

GitLab

Discord

Use enabled providers in the UI

Full example: enabling multiple providers

Troubleshooting

See also

Manage auth configuration

Build auth UI

Getting started

Concepts

Build

Deploy

Documentation Index

​The shape of every provider setup

​Callback URL

​Fixed var and secret names

​Google

​GitHub

​GitLab

​Discord

​Use enabled providers in the UI

​Full example: enabling multiple providers

​Troubleshooting

​See also

Manage auth configuration

Build auth UI

The shape of every provider setup

Callback URL

Fixed var and secret names

Google

GitHub

GitLab

Discord

Use enabled providers in the UI

Full example: enabling multiple providers

Troubleshooting

See also