Send User to Nav

In order to send users to our embedded finance application, you will need to create an endpoint that will perform the following tasks:

• Accept and forward the parameter redirect_uri
• Authenticate the current user
• Request a one-time authentication code for the current user
• Direct the user to our handshake endpoint with the one-time code and redirect_uri parameters: https://{PARTNER_SUBDOMAIN}.nav.com/partner/handshake?code={AUTHENTICATION_CODE}&redirect_uri={REDIRECT_URI}

We will need to know the URL for this endpoint to be used in CTAs and email campaigns

Nav Handshake Endpoint

The handshake endpoint is used as an entrypoint to our embedded finance application. Its main purpose is to log the user into our system using a one-time authentication code, then redirect the user to the supplied redirect_uri or our application's home page

Environment	URL
Sandbox	https://{PARTNER_SUBDOMAIN}.sandbox.nav.com/partner/handshake
Production	https://{PARTNER_SUBDOMAIN}.nav.com/partner/handshake

Parameters

The parameters can be provided as GET query params or POST body params

Parameter	Description
code.	Required. Authentication code retrieved from createAuthCode GraphQL mutation
redirect_uri	Optional. Default: /partner/home. Where to redirect the user on handshake success. Must start with a leading slash /. This is useful for sending users directly to our credit card offers /partner/financing/credit-cards.
no_redirect	Optional. Accepts boolean or "true". Perform the handshake, sign the user in, and respond with an empty 204 without redirecting

NodeJS Express Example

import express from 'express'
import fetch from 'node-fetch'
import authenticate from './authenticate'
import doesNavAccountExist from './does-nav-account-exist'
import createNavAccount from './create-nav-account'

const app = express()
const port = 80

const getNavAuthCode = async (userID) => {
  // Use GraphQL to request an Authentication Code
  const response = await fetch('https://api.nav.com/partners/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'my-secret-api-key',
      'x-partner-id': 'my-partner-id',
    },
    body: JSON.stringify({
      query: `
        mutation CreateAuthCode($userID: String!) {
          createAuthCode(userID: $userID)
        }
      `,
      variables: {
        userID: userID
      }
    })
  })
  const responseData = await response.json()

  return responseData.data.createAuthCode
}

app.get('/nav-redirect', async (req, res) => {
  // Authenticate the user
  const user = await authenticate(req)

  // Make sure the user's Nav account exists
  const navAccountExists = await doesNavAccountExist(user)
  if (!navAccountExists) {
    await createNavAccount(user)
  }

  // Get a one-time code to authenticate the user into our system
  const authCode = await getNavAuthCode(user.id)

  // Construct the handshake request parameters
  const params = new URLSearchParams({
    // Include all supplied params like `redirect_uri`
    ...req.params,
    code: authCode,
  })

  // Redirect the user to our site
  res.redirect(`https://my-subdomain.nav.com/partner/handshake?${params.toString()}`)
})

app.listen(port)