Custom Authentication

On this page


Stitch allows developers to issue custom credentials to users of their app. Custom authentication requires each user to have an ID which is unique within the app.

To get started with custom authentication for your app:

  1. Select Authentication from the MongoDB Stitch admin console left-side navigation
  2. Click the Edit button in the Custom Authentication row.
  3. Toggle the switch to enable custom authentication.
  4. Select desired optional user metadata.
  5. The Signing Key is part of the JSON Web Token which the application client exchanges with the server. Each app has a unique signing key which allows it to identify authenticated client requests. You can refer back to your signing key here when you are ready to start creating JWTs.


Custom authentication uses JSON Web Tokens (JWT), an open, industry standard RFC 7519 method for representing claims securely between two parties. A JWT consists of three parts: a header, a payload and a signature.

The header looks like this:

  "alg": "HS256",
  "typ": "JWT"

The payload is an object with some fields common to all JWTs and some which are particular to MongoDB Stitch. A JWT for use with MongoDB Stitch custom authentication uses have the following fields:

  "aud": "clientAppID",
  "sub": "uniqueUserID",
  "exp": 1495578429,
  "iat": 1495574829,
  "nbf": 1495578429,
  "stitch_meta": {
    "email": "",
    "name": "Joe Bloggs",
    "picture": ""

The payload fields are populated as follows:

Field Required/Optional Description
Required Audience. Populate with the App ID for your client application.
Required Expires. Number containing a NumericDate value indicating the time at which the token expires. MongoDB Stitch will not accept expired tokens for authentication.
Required Subject. A unique user ID in your authentication system.
Optional Issued at. Number containing a NumericDate value indicating the time at which the token should become valid.
Optional Not before. Functionally identical to iat.

Document that contains the following client application user data:

  • client
  • name
  • picture

The token’s signature consists of a hash of the header, the payload, and your signing token.


For web apps, you can create a signature for your token with a JavaScript library such as jsrsasign.

var sJWT = KJUR.jws.JWS.sign("HS256", sHeader, sPayload, "<your-signing-key>");

In the above operation, sHeader is the header, sPayload is your payload, and <your-signing-key> is the signing key you received from when you enabled custom authentication. sJWT is the resulting signed token.

For Android apps, you can create JSON web tokens in Java with a tool such as jjwt. See the documentation for setup and usage instructions.

Once you have a signed token, you can send it in a POST request to MongoDB Stitch and receive authenticated session data in return, as shown below.

curl -H "Content-Type:text/plain" --data 'my-signed-token' \<my-app-id>/auth/providers/custom-token/login

The response resembles the following:

{ "refreshToken": "very-long-string",
  "accessToken": "even-longer-string",
  "user": {
    "domainId": "58f1314cb4d53a4e4be4f88a",
    "_id": "5926018e57e0fa2b9f792b38",
    "identities": [ {
      "id": "my-custom-id",
      "provider": "custom/token"
    } ],
    "data": {},
    "sessionsValidSince": 1495662990,
    "type": "normal"
  "deviceId": "000000000000000000000000",
  "provider": "custom/token"