Studio

Auth Providers

Configure authentication providers to control access to Nuxt Studio.

Auth providers handle user authentication and access control for Studio. They determine who can log in and edit content.

Auth providers are different from Git providers. Auth providers handle user authentication, while Git providers handle repository operations.

Provider Comparison

Feature	GitHub OAuth	GitLab OAuth	Google OAuth	Custom Auth
Authentication	✅	✅	✅	✅
Git Operations	✅ Automatic (OAuth token)	✅ Automatic (OAuth token)	⚠️ Requires PAT	⚠️ Requires PAT
Access Control	✅ OAuth scope	✅ OAuth scope	⚠️ Moderator whitelist	⚠️ Custom logic
Secured Auth Flow	✅ Provider-managed	✅ Provider-managed	✅ Provider-managed	⚠️ Self-managed

You can use multiple providers simultaneously. For example, use GitHub OAuth for developers and Google OAuth for non-technical content editors.

Built-in Providers

GitHub

GitHub OAuth provides authentication with automatic Git access. Users who authenticate via GitHub can immediately push changes to the repository.

Navigate to GitHub Developer Settings

Go to GitHub Developer Settings and click New OAuth App

Configure the OAuth Application

Fill in the required fields:

Application name: Your app name
Homepage URL: https://yourdomain.com
Authorization callback URL: https://yourdomain.com/__nuxt_studio/auth/github

For local development, add: http://localhost:3000/__nuxt_studio/auth/github

Copy Your Credentials

After creating the OAuth app, you'll receive:

A Client ID (visible immediately)
A Client Secret (click Generate a new client secret)

Set Environment Variables

Add the GitHub OAuth credentials to your deployment platform's environment variables or .env file:

.env

STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
# Optional: Restrict access to specific users
# STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com

GitLab

GitLab OAuth provides authentication with automatic Git access. Users who authenticate via GitLab can immediately push changes to the repository.

Navigate to GitLab Applications

Go to your GitLab User Settings → Applications (or your group/organization settings) and create a New Application.

Configure the OAuth Application

Fill in the required fields:

Application name: Your app name
Redirect URI: https://yourdomain.com/__nuxt_studio/auth/gitlab
Scopes: Select api (required for publication)

For local development, add: http://localhost:3000/__nuxt_studio/auth/gitlab

Copy Your Credentials

After creating the OAuth application, you'll receive:

An Application ID (visible immediately)
A Secret (visible immediately)

Set Environment Variables

Add the GitLab OAuth credentials to your deployment platform's environment variables or .env file:

.env

STUDIO_GITLAB_APPLICATION_ID=<your_gitlab_application_id>
STUDIO_GITLAB_CLIENT_SECRET=<your_gitlab_secret>
# Optional: Restrict access to specific users
# STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com

Google

Google OAuth is ideal for non-technical users who don't have GitHub or GitLab accounts.

Navigate to Google Cloud Console

Go to Google Cloud Console and select or create a project, then navigate to APIs & Services → Credentials.

Create OAuth Application

Click Create Credentials and OAuth client ID and select Web application as the application type.

Fill in the required fields:

Name: Your app name
Authorized redirect URIs: https://yourdomain.com/__nuxt_studio/auth/google

For local development, add: http://localhost:3000/__nuxt_studio/auth/google

After creating the OAuth client, you'll receive:

A Client ID
A Client Secret

Save these credentials immediately; you may not be able to view them again.

Create a Personal Access Token

Since Google doesn't provide Git access, you must also configure a Personal Access Token for repository operations.

Set Environment Variables

Add the Google OAuth credentials, your personal access token and moderator list:

.env

STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com

.env

STUDIO_GOOGLE_CLIENT_ID=<your_google_client_id>
STUDIO_GOOGLE_CLIENT_SECRET=<your_google_client_secret>
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com

The STUDIO_GOOGLE_MODERATORS environment variable is required for Google OAuth. Only users with email addresses in this list can access Studio.

Custom Authentication

For complete control over authentication, you can implement your own auth logic (password forms, SSO, LDAP, etc.) using Studio's session utilities.

When using custom authentication, you are fully responsible for securing your authentication flow. Studio only manages the session after you authenticate the user.

Personal Access Token Required

You must configure a Personal Access Token for repository operations based on the Git provider you are using.

.env

# For GitHub repositories
STUDIO_GITHUB_TOKEN=<your_github_personal_access_token>

# For GitLab repositories
STUDIO_GITLAB_TOKEN=<your_gitlab_personal_access_token>

See Git Providers for instructions on creating a PAT.

Implementation Flow

Validate the user in your login handler using your preferred method (password, SSO, etc.)
Create the session by calling setStudioUserSession(event, user) with a StudioUserSession object
Handle logout by calling clearStudioUserSession(event) to clear the session

Required Session Fields

When calling setStudioUserSession, you must provide:

Field	Type	Required	Description
`name`	`string`	✅	Display name for the user
`email`	`string`	✅	User's email address
`providerId`	`string`	❌	Unique identifier for the user
`avatar`	`string`	❌	URL to user's avatar image

server/api/studio/login.ts

import { eventHandler, readBody, createError } from 'h3'
import { setStudioUserSession } from '#imports'

export default eventHandler(async (event) => {
  const { email, password } = await readBody<{ email?: string, password?: string }>(event)

  // ⚠️ Implement your own secure validation logic here
  // This is a simplified example - use proper password hashing and validation
  const user = await validateCredentials(email, password)

  if (!user) {
    throw createError({
      statusCode: 401,
      message: 'Invalid credentials'
    })
  }

  await setStudioUserSession(event, {
    providerId: user.id,
    name: user.name,
    email: user.email,
    avatar: user.avatar || ''
  })

  return { ok: true }
})

Example: Logout Handler

server/api/studio/logout.ts

import { eventHandler } from 'h3'
import { clearStudioUserSession } from '#imports'

export default eventHandler(async (event) => {
  await clearStudioUserSession(event)
  return { ok: true }
})

After successfully setting the session, redirect users to your app root (/). Studio will automatically detect the session and activate for that user.

server/api/studio/login.ts

// After setStudioUserSession...
return sendRedirect(event, '/')

Advanced Options

Access Control with Moderators

You can restrict access to Studio by defining a whitelist of authorized users through the STUDIO_{PROVIDER}_MODERATORS environment variable.

.env

# GitHub OAuth moderators
STUDIO_GITHUB_MODERATORS=admin@example.com,editor@example.com

# GitLab OAuth moderators
STUDIO_GITLAB_MODERATORS=admin@example.com,editor@example.com

# Google OAuth moderators (required)
STUDIO_GOOGLE_MODERATORS=admin@example.com,editor@example.com

The moderator list is a comma-separated list of email addresses. Only users with matching email addresses will be granted access.

Behavior by Provider

Provider	Moderator List	Behavior
GitHub OAuth	Optional	If empty, all OAuth-authenticated users have access
GitLab OAuth	Optional	If empty, all OAuth-authenticated users have access
Google OAuth	Required	Without moderators, no one can access Studio
Custom Auth	N/A	Implement your own access control logic

For GitHub and GitLab OAuth, repository write access is still controlled by OAuth scopes, preventing unauthorized users from pushing changes even if they can access Studio.

Custom Redirect URL

By default, Studio uses your deployment URL for OAuth callbacks. To customize the redirect URL:

.env

# GitHub OAuth
STUDIO_GITHUB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/github

# GitLab OAuth
STUDIO_GITLAB_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/gitlab

# Google OAuth
STUDIO_GOOGLE_REDIRECT_URL=https://custom-domain.com/__nuxt_studio/auth/google

This is useful when you need to handle OAuth callbacks through a specific endpoint, such as behind a reverse proxy or with custom domain routing.

Once deployed with the appropriate credentials set as environment variables, Studio will be accessible from your production instance. Navigate to /_studio (or your configured route) to start editing and publishing content.

Edit this pageorReport an issue

Git Providers

Configure Git providers to synchronize content between your production website and your Git repository.

Content Editors

Discover and select your favorite way to manage your content between the visual or the code editor.