0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/auth/cloud
History 2026-11-12 21:12:29 +00:00
..
src feat: pass the authenticated user to DynamicArgument callbacks (#28612) 2026-11-12 10:55:12 -05:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
cloud-auth.md feat: auth core, server RBAC, and adapter permission enforcement (#13163) 2026-03-03 22:49:10 +01:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
oxlint.config.ts refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
README.md chore(*): Update/unify/add READMEs (#22858) 2026-09-02 14:36:59 +02:00
tsconfig.build.json feat: auth core, server RBAC, and adapter permission enforcement (#13163) 2026-03-03 22:49:10 +01:00
tsconfig.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
tsdown.config.ts chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
turbo.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
vitest.config.ts feat: auth core, server RBAC, and adapter permission enforcement (#13163) 2026-03-03 22:49:10 +01:00

@mastra/auth-cloud

@mastra/auth-cloud authenticates users through Mastra Cloud with a Proof Key for Code Exchange (PKCE) OAuth flow. Use it when a self-hosted Mastra server should delegate sign-in and session management to a Mastra Cloud project.

Installation

npm install @mastra/auth-cloud

Usage

Set MASTRA_PROJECT_ID before starting Mastra.

import { MastraCloudAuthProvider } from '@mastra/auth-cloud';
import { Mastra } from '@mastra/core/mastra';

export const mastra = new Mastra({
  server: {
    auth: new MastraCloudAuthProvider({
      projectId: process.env.MASTRA_PROJECT_ID!,
      cloudBaseUrl: 'https://cloud.mastra.ai',
      callbackUrl: 'https://example.com/auth/callback',
      isProduction: process.env.NODE_ENV === 'production',
    }),
  },
});

Documentation

MastraCloudAuthProvider implements Mastra's user, single sign-on, and session provider interfaces. It sends users through Mastra Cloud's PKCE authorization flow, validates the resulting session cookie, and accepts bearer tokens for API clients that do not use browser cookies.

The constructor requires the Mastra Cloud projectId, the cloudBaseUrl, and the absolute OAuth callbackUrl registered for the application. Set isProduction to add the Secure attribute to authentication cookies. The provider also accepts the common Mastra auth options for public and protected routes and custom user authorization.

During sign-in, the provider creates a PKCE verifier and challenge, redirects the browser to Mastra Cloud, exchanges the returned authorization code, and stores the session in an HTTP-only cookie. It exposes the login, callback, logout, session validation, and session refresh behavior required by Mastra's server authentication middleware.

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.