Self-Mint JWT Tokens for API Authentication – Yext Help

Minting your own tokens lets you make secure calls to the Yext APIs. You can mint tokens using a library in your preferred programming language. This article covers how to access your signing key and mint a token, with examples in Python and Node.js.

After minting a token, pass it as an Authorization header on your API calls.

Access Your Signing Key

Click Developer in the navigation bar, then click Developer Console.
Select the relevant app in the Your Apps section.
Click the API Credentials tab.
Click Generate Custom Tokens with a Signing Key

This opens a section showing your Signing Key and Key ID.

Mint a Token

In your code, use a library to mint a JWT token.

Provide the Signing Key ID as the kid in the JWT header.
Use the Signing Key to sign the JWT token.

Include the properties below in your JWT claims, depending on the logic you want to enforce:

Property	Type	Details	Required?
`name`	string	The name of your token. This can be anything, but note it, since you need it to configure your Search experience.	Required
`kid`	string	The API key ID of the app that has permission to access the desired endpoint. Find the Key ID in an app's Developer Console, under the API Credentials tab, by clicking Generate Custom Tokens with a Secret Key.	Required
`claims`	object	Configures what the token authorizes. See the claims sub-properties below.	Required
`scope`	string	A regex that specifies paths in the site. Yext only generates tokens for pages matching this path's regex, which can improve performance. If not set, Yext generates a token for every page in the site.	Optional

Claims sub-properties:

Sub-property	Details
`aud`	Required. A URL, or array of URLs, specifying which endpoints the token can call. Must start with `/v2/accounts/` followed by a path to at least a single endpoint, in the form `/v2/accounts/{businessId}/endpoint/{optionalPath}`. Set `businessId` to any business ID, or to `me` for the business ID calling the app. The optional path can restrict the token further, for example to a single stream.
`exp`	The token's expiration time, in Unix time (conversion tool). If omitted, the token doesn't expire.
`query`	Optional additional query parameters, such as `experienceKey` or `v`. Leave empty if not needed.

Example

Assume a business creates an app with:

Signing Key: a022f72638164ca18b6f92f15d551b99
Signing Key ID: y0M8ZSAVtTS7T8utw-bIOw

The JWT header for any token created by this app looks like:

{
  "typ": "JWT",
  "alg": "HS256",
  "kid": "y0M8ZSAVtTS7T8utw-bIOw"
}

With unnecessary whitespace removed and base64url encoded, this gives a JWT header of:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6InkwTThaU0FWdFRTN1Q4dXR3LWJJT3cifQ

Suppose you want the token to only have access to the "MySearchExperience" experience, and only be able to make calls to the Search API endpoints. Set the token to expire at 2021-01-02T03:04:05Z (for the code examples below, the token expires after 1 hour instead).

The claims object looks like:

{
  "aud": "/v2/accounts/me/search",
  "exp": 1609556645,
  "query": {
    "experienceKey": "MySearchExperience"
  }
}

Putting the header and claims together, signed with the API key, yields the full JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InkwTThaU0FWdFRTN1Q4dXR3LWJJT3cifQ.eyJhdWQiOiIvdjIvYWNjb3VudHMvbWUvYW5zd2VycyIsImV4cCI6MTYwOTU1NjY0NSwicXVlcnkiOnsiZXhwZXJpZW5jZUtleSI6Ik15QW5zd2Vyc0V4cGVyaWVuY2UifX0.TiydOR4NwW-MwMV8UGlAgvVmSiFYQiw2gA5ofYdM9Pw

Python:

Using the PyJWT library:

import jwt
from datetime import datetime, timedelta


token = jwt.encode(
  {
    "aud": "/v2/accounts/me/search",
    "exp": datetime.utcnow() + timedelta(hours=1),
    "query": {
      "experienceKey": "MySearchExperience"
    }
  },
  "a022f72638164ca18b6f92f15d551b99",
  headers={"kid": "y0M8ZSAVtTS7T8utw-bIOw"})

Node.js:

Using the jsonwebtoken library, which has convenient syntax for the kid header and exp claim:

var jwt = require('jsonwebtoken');

var token = jwt.sign(
  {
    "aud": "/v2/accounts/me/search",
    "query": {
      "experienceKey": "MySearchExperience"
    }
  },
  "a022f72638164ca18b6f92f15d551b99",
  {keyid: "y0M8ZSAVtTS7T8utw-bIOw", expiresIn: