[][open-collective-link] [][open-collective-link]

Parse Server is an open source backend that can be deployed to any infrastructure that can run Node.js. Parse Server works with the Express web application framework. It can be added to existing web applications, or run by itself.

The full documentation for Parse Server is available in the wiki. The Parse Server guide is a good place to get started. An API reference and Cloud Code guide are also available. If you're interested in developing for Parse Server, the Development guide will help you get set up.

A big thank you 🙏 to our sponsors and backers who support the development of Parse Platform!

Bronze Sponsors

• Flavors & Branches
  • Long Term Support
• Getting Started
  • Running Parse Server
    • Compatibility
      • Node.js
      • MongoDB
      • PostgreSQL
    • Locally
    • Docker Container
    • Saving and Querying Objects
    • Connect an SDK
  • Running Parse Server elsewhere
    • Sample Application
    • Parse Server + Express
  • Parse Server Health
    • Status Values
• Configuration
  • Basic Options
  • Client Key Options
  • Access Scopes
  • Route Allow List
    • Covered Routes
  • Email Verification and Password Reset
  • Password and Account Policy
  • Custom Routes
    • Example
    • Reserved Paths
    • Parameters
  • Custom Pages
  • Using Environment Variables
  • Available Adapters
  • Configuring File Adapters
    • Restricting File URL Domains
  • Idempotency Enforcement
  • Installations
    • Options
      • duplicateDeviceTokenActionEnforceAuth
      • duplicateDeviceTokenAction
      • duplicateDeviceTokenMergePriority
    • Configuration example
  • Localization
    • Pages
      • Localization with Directory Structure
      • Localization with JSON Resource
      • Dynamic placeholders
      • Reserved Keys
      • Parameters
  • Multi-Tenancy
  • Logging
• Deprecations
• Live Query
• GraphQL
  • Running
    • Using the CLI
    • Using Docker
    • Using Express.js
  • Checking the API health
  • Creating your first class
  • Using automatically generated operations
  • Customizing your GraphQL Schema
  • Learning more
• Contributing
• Contributors
• Sponsors
• Backers

Flavors & Branches

Parse Server is available in different flavors on different branches:

• The main branches are [release][log_release] and [alpha][log_alpha]. See the changelog overview for details.
• The long-term-support (LTS) branches are named release-.x.x, for example release-5.x.x. LTS branches do not have pre-release branches.

Long Term Support

Long-Term-Support (LTS) is provided for the previous Parse Server major version. For example, Parse Server 5.x will receive security updates until Parse Server 6.x is superseded by Parse Server 7.x and becomes the new LTS version. While the current major version is published on branch release, a LTS version is published on branch release-#.x.x, for example release-5.x.x for the Parse Server 5.x LTS branch.

⚠️ LTS versions are provided to help you transition as soon as possible to the current major version. While we aim to fix security vulnerabilities in the LTS version, our main focus is on developing the current major version and preparing the next major release. Therefore we may leave certain vulnerabilities up to the community to fix. Search for pull requests with the specific LTS base branch to see the current open vulnerabilities for that LTS branch.

Getting Started

The fastest and easiest way to get started is to run MongoDB and Parse Server locally.

Running Parse Server

Before you start make sure you have installed:

• NodeJS that includes npm
• MongoDB or PostgreSQL(with PostGIS 2.2.0 or higher)
• Optionally Docker

Compatibility

Node.js

Parse Server is continuously tested with the most recent releases of Node.js to ensure compatibility. We follow the Node.js Long Term Support plan and only test against versions that are officially supported and have not reached their end-of-life date.

_{(1) Parse.Object.createdAt, Parse.Object.updatedAt.}

[!NOTE] In Cloud Code, both masterKey and readOnlyMasterKey set request.master to true. To distinguish between them, check request.isReadOnly. For example, use request.master && !request.isReadOnly to ensure full master key access.

Route Allow List

The routeAllowList option restricts which REST API routes are accessible to external clients. When set, all external REST API requests are denied by default unless the route matches one of the configured regex patterns. This is useful for apps where all logic runs in Cloud Code and clients should not access the REST API directly.

Internal calls from Cloud Code, Cloud Jobs, and triggers are not affected. Master key and maintenance key requests bypass the restriction.

const server = ParseServer({
  ...otherOptions,
  routeAllowList: [
    'classes/ChatMessage',
    'classes/Public.*',
    'users',
    'login',
    'functions/getMenu',
    'health',
  ],
});

Each entry is a regex pattern matched against the normalized route identifier. Patterns are auto-anchored with ^ and $ for full-match semantics. For example, classes/Chat matches only classes/Chat, not classes/ChatRoom. Use classes/Chat.* to match both.

Setting an empty array [] blocks all external non-master-key REST API requests (full lockdown of REST API routes). Not setting the option preserves current behavior (all routes accessible).

Covered Routes

The following table lists all route groups covered by routeAllowList with examples of how to allow them.

[!NOTE] File routes are not covered by routeAllowList. File upload access is controlled via the fileUpload option. File download and metadata access is controlled via the fileDownload option.

[!NOTE] The GraphQL API is not covered by routeAllowList. routeAllowList gates the REST API per route, while every GraphQL operation is transported over a single endpoint with the operation, target class, and field set encoded in the request body — so per-route allow-list semantics do not compose with it.

[!NOTE] The Pages API is not covered by routeAllowList. Its routes (default endpoint apps, configurable via pages.pagesEndpoint) serve the browser pages for email verification and password reset that Parse Server links to in the emails it sends to end users, so they must remain reachable without any Parse credentials and are not part of the client REST API. Their behavior is controlled by the email verification and password reset options (verifyUserEmails, emailAdapter) and the pages option.

Email Verification and Password Reset

Verifying user email addresses and enabling password reset via email requires an email adapter. There are many email adapters provided and maintained by the community. The following is an example configuration with an example email adapter. See the [Parse Server Options][server-options] for more details and a full list of available options.

const server = ParseServer({
  ...otherOptions,

  // Enable email verification
  verifyUserEmails: true,

  // Set email verification token validity to 2 hours
  emailVerifyTokenValidityDuration: 2 * 60 * 60,

  // Set email adapter
  emailAdapter: {
    module: 'example-mail-adapter',
    options: {
      // Additional adapter options
      ...mailAdapterOptions,
    },
  },
});

Offical email adapters maintained by Parse Platform:

• parse-server-api-mail-adapter (localization, templates, universally supports any email provider)

Email adapters contributed by the community:

• parse-smtp-template (localization, templates)
• parse-server-postmark-adapter
• parse-server-sendgrid-adapter
• parse-server-mandrill-adapter
• parse-server-simple-ses-adapter
• parse-server-mailgun-adapter-template
• parse-server-sendinblue-adapter
• parse-server-mailjet-adapter
• simple-parse-smtp-adapter
• parse-server-generic-email-adapter

Password and Account Policy

Set a password and account policy that meets your security requirements. The following is an example configuration. See the [Parse Server Options][server-options] for more details and a full list of available options.

const server = ParseServer({
  ...otherOptions,

  // The account lock policy
  accountLockout: {
    // Lock the account for 5 minutes.
    duration: 5,
    // Lock an account after 3 failed log-in attempts
    threshold: 3,
    // Unlock the account after a successful password reset
    unlockOnPasswordReset: true,
  },

  // The password policy
  passwordPolicy: {
    // Enforce a password of at least 8 characters which contain at least 1 lower case, 1 upper case and 1 digit
    validatorPattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.{8,})/,
    // Do not allow the username as part of the password
    doNotAllowUsername: true,
    // Do not allow to re-use the last 5 passwords when setting a new password
    maxPasswordHistory: 5,
  },
});

Custom Routes

Custom routes allow to build user flows with webpages, similar to the existing password reset and email verification features. Custom routes are defined with the pages option in the Parse Server configuration:

Example

const api = new ParseServer({
  ...otherOptions,

  pages: {
    customRoutes: [{
      method: 'GET',
      path: 'custom_route',
      handler: async request => {
        // custom logic
        // ...
        // then, depending on the outcome, return a HTML file as response
        return { file: 'custom_page.html' };
      }
    }]
  }
}

The above route can be invoked by sending a GET request to: https://[parseServerPublicUrl]/[parseMount]/[pagesEndpoint]/[appId]/[customRoute]

The handler receives the request and returns a custom_page.html webpage from the pages.pagesPath directory as response. The advantage of building a custom route this way is that it automatically makes use of Parse Server's built-in capabilities, such as page localization and dynamic placeholders.

Reserved Paths

The following paths are already used by Parse Server's built-in features and are therefore not available for custom routes. Custom routes with an identical combination of path and method are ignored.

Parameters

Custom Pages

It’s possible to change the default pages of the app and redirect the user to another path or domain.

const server = ParseServer({
  ...otherOptions,

  customPages: {
    passwordResetSuccess: 'http://yourapp.com/passwordResetSuccess',
    verifyEmailSuccess: 'http://yourapp.com/verifyEmailSuccess',
    parseFrameURL: 'http://yourapp.com/parseFrameURL',
    linkSendSuccess: 'http://yourapp.com/linkSendSuccess',
    linkSendFail: 'http://yourapp.com/linkSendFail',
    invalidLink: 'http://yourapp.com/invalidLink',
    invalidVerificationLink: 'http://yourapp.com/invalidVerificationLink',
    choosePassword: 'http://yourapp.com/choosePassword',
  },
});

Using Environment Variables

You may configure the Parse Server using environment variables:

PORT
PARSE_SERVER_APPLICATION_ID
PARSE_SERVER_MASTER_KEY
PARSE_SERVER_DATABASE_URI
PARSE_SERVER_URL
PARSE_SERVER_CLOUD

The default port is 1337, to use a different port set the PORT environment variable:

$ PORT=8080 parse-server --appId APPLICATION_ID --masterKey MASTER_KEY

For the full list of configurable environment variables, run parse-server --help or take a look at Parse Server Configuration.

Available Adapters

All official adapters are distributed as scoped packages on npm (@parse).

Some well maintained adapters are also available on the Parse Server Modules organization.

You can also find more adapters maintained by the community by searching on npm.

Configuring File Adapters

Parse Server allows developers to choose from several options when hosting files:

• GridFSBucketAdapter - which is backed by MongoDB
• S3Adapter - which is backed by Amazon S3
• GCSAdapter - which is backed by Google Cloud Storage
• FSAdapter - local file storage

GridFSBucketAdapter is used by default and requires no setup, but if you're interested in using Amazon S3, Google Cloud Storage, or local file storage, additional configuration information is available in the Parse Server guide.

Restricting File URL Domains

Parse objects can reference files by URL. To prevent SSRF attacks via crafted file URLs, you can restrict the allowed URL domains using the fileUpload.allowedFileUrlDomains option.

This protects against scenarios where an attacker provides a Parse.File with an arbitrary URL, for example as a Cloud Function parameter or in a field of type Object or Array. If Cloud Code or a client calls getData() on such a file, the Parse SDK makes an HTTP request to that URL, potentially leaking the server or client IP address and accessing internal services.

[!NOTE] Fields of type Parse.File in the Parse schema are not affected by this attack, because Parse Server discards the URL on write and dynamically generates it on read based on the file adapter configuration.

const parseServer = new ParseServer({
  ...otherOptions,
  fileUpload: {
    allowedFileUrlDomains: ['cdn.example.com', '*.example.com'],
  },
});

• ['*'] (default) allows file URLs with any domain.
• ['cdn.example.com'] allows only exact hostname matches.
• ['*.example.com'] allows any subdomain of example.com.
• [] blocks all file URLs; only files referenced by name are allowed.

Idempotency Enforcement

Caution, this is an experimental feature that may not be appropriate for production.

This feature deduplicates identical requests that are received by Parse Server multiple times, typically due to network issues or network adapter access restrictions on mobile operating systems.

Identical requests are identified by their request header X-Parse-Request-Id. Therefore a client request has to include this header for deduplication to be applied. Requests that do not contain this header cannot be deduplicated and are processed normally by Parse Server. This means rolling out this feature to clients is seamless as Parse Server still processes requests without this header when this feature is enabled.

This feature needs to be enabled on the client side to send the header and on the server to process the header. Refer to the specific Parse SDK docs to see whether the feature is supported yet.

Deduplication is only done for object creation and update (POST and PUT requests). Deduplication is not done for object finding and deletion (GET and DELETE requests), as these operations are already idempotent by definition.

Configuration example

let api = new ParseServer({
    idempotencyOptions: {
        paths: [".*"],       // enforce for all requests
        ttl: 120             // keep request IDs for 120s
    }
}

Parameters

Postgres

To use this feature in Postgres, you will need to create a cron job using pgAdmin or similar to call the Postgres function idempotency_delete_expired_records() that deletes expired idempotency records. You can find an example script below. Make sure the script has the same privileges to log into Postgres as Parse Server.

#!/bin/bash

set -e
psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
    SELECT idempotency_delete_expired_records();
EOSQL

exec "$@"

Assuming the script above is named, parse_idempotency_delete_expired_records.sh, a cron job that runs the script every 2 minutes may look like:

2 * * * * /root/parse_idempotency_delete_expired_records.sh >/dev/null 2>&1

Installations

Parse Server deduplicates _Installation records when a new install collides with an existing row's deviceToken. The installation option block configures the dedup behavior.

Options

duplicateDeviceTokenActionEnforceAuth

When true, the dedup operation runs with the caller's auth context so ACL and CLP are honored. When false, the dedup runs as master and bypasses both. Master and maintenance keys always bypass regardless of this flag.

Because what this option enforces is the ACL and the class-level permissions, it has no effect on its own for a record that carries no ACL under permissive class-level permissions. To scope the deduplication, combine this option with either an ACL on _Installation records or class-level permissions that withhold the delete operation from the caller.

duplicateDeviceTokenAction

What Parse Server does to the conflicting _Installation row(s) when a new install's deviceToken collides with an existing row.

• 'delete': destroys the conflicting row.
• 'update': clears the now-conflicting ID field on the conflicting row, preserving custom fields, channels, and history.

duplicateDeviceTokenMergePriority

When an existing row holds the new deviceToken but has no installationId of its own, Parse Server merges the two rows. This option controls which side wins.

• 'deviceToken': the deviceToken-only row survives; the request's installationId-matched row is the loser.
• 'installationId': the request's installationId-matched row survives; the deviceToken-only orphan is the loser.

Configuration example

const parseServer = new ParseServer({
  ...otherOptions,
  installation: {
    duplicateDeviceTokenActionEnforceAuth: true,
    duplicateDeviceTokenAction: 'update',
    duplicateDeviceTokenMergePriority: 'installationId',
  },
});

Localization

Pages

Custom pages as well as feature pages (e.g. password reset, email verification) can be localized with the pages option in the Parse Server configuration:

const api = new ParseServer({
  ...otherOptions,

  pages: {
    enableLocalization: true,
  }
}

Localization is achieved by matching a request-supplied locale parameter with localized page content. The locale can be supplied in either the request query, body or header with the following keys:

• query: locale
• body: locale
• header: x-parse-page-param-locale

For example, a password reset link with the locale parameter in the query could look like this:

http://example.com/parse/apps/[appId]/request_password_reset?token=[token]&username=[username]&locale=de-AT

• Localization is only available for pages in the pages directory as set with pages.pagesPath.
• Localization for feature pages (e.g. password reset, email verification) is disabled if pages.customUrls are set, even if the custom URLs point to the pages within the pages path.
• Only .html files are considered for localization when localizing custom pages.

Pages can be localized in two ways:

Localization with Directory Structure

Pages are localized by using the corresponding file in the directory structure where the files are placed in subdirectories named after the locale or language. The file in the base directory is the default file.

Example Directory Structure:

root/
├── public/                  // pages base path
│   ├── example.html         // default file
│   └── de/                  // de language folder
│   │   └── example.html     // de localized file
│   └── de-AT/               // de-AT locale folder
│   │   └── example.html     // de-AT localized file

Files are matched with the locale in the following order:

1. Locale match, e.g. locale de-AT matches file in folder de-AT.
2. Language match, e.g. locale de-CH matches file in folder de.
3. Default; file in base folder is returned.

Configuration Example:

const api = new ParseServer({
  ...otherOptions,

  pages: {
    enableLocalization: true,
    customUrls: {
      passwordReset: 'https://example.com/page.html'
    }
  }
}

Pros:

• All files are complete in their content and can be easily opened and previewed by viewing the file in a browser.

Cons:

• In most cases, a localized page differs only slightly from the default page, which could cause a lot of duplicate code that is difficult to maintain.

Localization with JSON Resource

Pages are localized by adding placeholders in the HTML files and providing a JSON resource that contains the translations to fill into the placeholders.

Example Directory Structure:

root/
├── public/                  // pages base path
│   ├── example.html         // the page containing placeholders
├── private/                 // folder outside of public scope
│   └── translations.json    // JSON resource file

The JSON resource file loosely follows the i18next syntax, which is a syntax that is often supported by translation platforms, making it easy to manage translations, exporting them for use in Parse Server, and even to automate this workflow.

Example JSON Content:

{
  "en": {               // resource for language `en` (English)
    "translation": {
      "greeting": "Hello!"
    }
  },
  "de": {               // resource for language `de` (German)
    "translation": {
      "greeting": "Hallo!"
    }
  }
  "de-AT": {            // resource for locale `de-AT` (Austrian German)
    "translation": {
      "greeting": "Servus!"
    }
  }
}

Configuration Example:

const api = new ParseServer({
  ...otherOptions,

  pages: {
    enableLocalization: true,
    localizationJsonPath: './private/localization.json',
    localizationFallbackLocale: 'en'
  }
}

Pros:

• There is only one HTML file to maintain that contains the placeholders that are filled with the translations according to the locale.

Cons:

• Files cannot be easily previewed by viewing the file in a browser because the content contains only placeholders and even HTML or CSS changes may be dynamically applied, e.g. when a localization requires a Right-To-Left layout direction.
• Style and other fundamental layout changes may be more difficult to apply.

Dynamic placeholders

In addition to feature related default parameters such as appId and the translations provided via JSON resource, it is possible to define custom dynamic placeholders as part of the router configuration. This works independently of localization and, also if enableLocalization is disabled.

Configuration Example:

const api = new ParseServer({
  ...otherOptions,

  pages: {
    placeholders: {
      exampleKey: 'exampleValue'
    }
  }
}

The placeholders can also be provided as function or as async function, with the locale and other feature related parameters passed through, to allow for dynamic placeholder values:

const api = new ParseServer({
  ...otherOptions,

  pages: {
    placeholders: async (params) => {
      const value = await doSomething(params.locale);
      return {
        exampleKey: value
      };
    }
  }
}

Reserved Keys

The following parameter and placeholder keys are reserved because they are used related to features such as password reset or email verification. They should not be used as translation keys in the JSON resource or as manually defined placeholder keys in the configuration: appId, appName, email, error, locale, publicServerUrl, token, username.

Parameters

Notes

• In combination with the Parse Server API Mail Adapter Parse Server provides a fully localized flow (emails -> pages) for the user. The email adapter sends a localized email and adds a locale parameter to the password reset or email verification link, which is then used to respond with localized pages.

Multi-Tenancy

Parse Server does not support multi-tenancy. Only one Parse Server instance may be mounted per Express app. Among other considerations, there is no isolation between apps in the same process. For example,