Minka Ledger Docs
How To Guides

How to authenticate with JWT


Ledger SDK allows users to authenticate to ledger by sending tokens.

The JWT options object (JwtConfig) has the following definition

type JwtConfig = {
  /**
   * Represents a client identifier.
   *
   */
  iss: string
 
  /**
   * Represents a user identifier of the token sender.
   *
   */
  sub: string
 
  /**
   * Represents a recipient for which a token is intended, ledger public key or handle
   *
   * */
  aud: string
 
  /**
   * Time after which a token expires, seconds since epoch.
   *
   */
  exp: number
 
  /**
   * Unique id of the token, can be used to prevent replay attacks
   *
   */
  jti?: string
 
  /**
   * Defines the request hash claim (hsh) must
   * be created and sent.
   *
   * Set as "true" if this value is not
   * given.
   */
  createHsh?: boolean
 
  /**
   * ED25519 Key pair for signing token
   *
   */
  keyPair: LedgerKeyPair
 
  /**
   * Token verification key identifier.
   * Accepts a public key or a ledger signer handle.
   */
  kid?: LedgerHandle | LedgerKeyPair['public']
}

JWT configuration can be set and mixed at three different levels - SDK, client and request.

SDK - Securing SDK instance

SDK can be secured when initializing a new object by using the property secure of SDK constructor options.

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
    format: 'ed25519-raw',
    public: '<your ledger public key>'
  },
  secure: {
    aud: '<token audience>',
    iss: '<token issuer>',
    keyPair: {
      public: '<signature public key>',
      format: '<signature key format>',
      secret: '<signature secret key>'
    },
    sub: '<token sub>',
    exp: 3600 // (1 hour)
    createHsh: true,
    kid: '<token verification key identifier>',
  }
})

This can also be set dynamically after creating a new instance with the method setAuthParams

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
    format: 'ed25519-raw',
    public: '<your ledger public key>'
  }
})
 
sdk.setAuthParams({
  aud: '<token audience>',
  iss: '<token issuer>',
  keyPair: {
	  public: '<signature public key>',
    format: '<signature key format>',
    secret: '<signature secret key>'
  },
  sub: '<token sub>',
  exp: 3600 // (1 hour)
  createHsh: true,
  kid: '<token verification key identifier>',
})

Client - Securing SDK Client

A client can be dynamically secured with the method setAuthParams

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
    format: 'ed25519-raw',
    public: '<your ledger public key>'
  }
})
 
// Securing wallet client
sdk.wallet.setAuthParams({
  aud: '<token audience>',
  iss: '<token issuer>',
  keyPair: {
    public: '<signature public key>',
    format: '<signature key format>',
    secret: '<signature secret key>'
  },
  sub: '<token sub>',
  exp: 3600 // (1 hour)
  createHsh: true,
  kid: '<token verification key identifier>',
})

Request - Securing a API call

A request can be dynamically secured with the method setAuthParams

import { LedgerSdk } from '@minka/ledger-sdk'
 
const sdk = new LedgerSdk({
  server: '<your ledger URL>',
  signer: {
		format: 'ed25519-raw',
		public: '<your ledger public key>'
	}
})
	
// Securing a search for a wallet 
const { wallet } = await sdk.wallet.read('wallet-handle', {
aud: '<token audience>',
  iss: '<token issuer>',
  keyPair: {
    public: '<signature public key>',
    format: '<signature key format>',
    secret: '<signature secret key>'
  },
  sub: '<token sub>',
  exp: 3600 // (1 hour)
  createHsh: true,
  kid: '<token verification key identifier>',
})

See About Authentication for more details.

On this page