Generating the URL

The base URL is, with parameters appended to it. For instance:

This URL structure adheres to the following interface:

You can use or the code below to generate the URL. The URL is to be distributed to your users via any communication method or directly in your frontend. The generated URL can be quite long, so you may consider using a URL shortener.

Nonce Generation

In order to avoid phishing attacks where a malicious party successfully gets a signature out of a user, you can implement a unique nonce generation scheme. The problem is that if the exact URL for a user (their challenge) is known / can be generated by a malicious party, they can generate the challenge message and phish the signature out of the user to authenticate as them.

However, if there is added randomness, a malicious party cannot know the exact challenge message. You can then check if the randomness is valid and issued by you before authentication to avoid these phishing attacks.


import { generateBitBadgesAuthUrl, CodeGenQueryParams } from 'bitbadgesjs-sdk';

const popupParams: CodeGenQueryParams {
} // See Authentication URL page

const authUrl = generateBitBadgesAuthUrl(popupParams);
export const generateBitBadgesAuthUrl = (params: CodeGenQueryParams) => {
  let url = ``;
  for (const [key, value] of Object.entries(params)) {
    if (value) {
      if (typeof value === 'object') {
        const valueString = JSON.stringify(value);
        const encodedValue = encodeURIComponent(valueString);
        url = url.concat(`${key}=${encodedValue}&`);
      } else {
        url = url.concat(`${key}=${value}&`);
  return url;

Last updated