#Overview

The Magic SDK for Node is your entry-point to secure, passwordless authentication for your application. This guide will cover some important topics for getting started with Node APIs and to make the most of Magic's features.

#Getting Started

The Magic class is the entry-point to the Magic SDK. It must be instantiated with a Magic secret key.

#Installation

01npm install @magic-sdk/admin

#Constructor

#Magic.init()

#Initialization

01const { Magic } = require('@magic-sdk/admin');

02

03let magic;

04

05// Construct with an API key:

06magic = await Magic.init('SECRET_API_KEY');

07

08// Construct with an API key plus options:

09magic =  await Magic.init('SECRET_API_KEY', { endpoint: '...' });

#Token Module

The Token Module and its members are accessible on the Magic Admin SDK instance by the token property.

01const { Magic } = require('@magic-sdk/admin');

02

03const magic = await Magic.init('SECRET_API_KEY');

04

05magic.token;

06magic.token.getIssuer;

07magic.token.getPublicAddress;

08magic.token.decode;

09magic.token.validate;

#getIssuer

#Arguments

• didToken (String): A Decentralized ID Token generated by a Magic user on the client-side.

#Returns

• A Decentralized ID (iss) of the Magic user who generated the DID Token

#getPublicAddress

Gets the cryptographic public address of the Magic User who generated the supplied token.

#Arguments

• didToken (String): A Decentralized ID Token generated by a Magic user on the client-side

#Returns

• The public address of the Magic User who generated the DID Token. Currently, this value is associated with the Ethereum blockchain.

#decode

Decodes a Decentralized ID Token from a Base64 string into a tuple of its individual components.

#Arguments

• didToken (String): A Decentralized ID Token generated by a Magic user on the client-side

#Returns

• proof (String): A digital signature that proves the validity of the given claim
• claim (Object): Unsigned data the user asserts. This should equal the proof after Elliptic Curve recovery. See Decentralized ID Token Specification for fields inside the claim.

The claim is automatically parsed to the following interface:

01interface Claim {

02  iat: number; // Issued At Timestamp

03  ext: number; // Expiration Timestamp

04  iss: string; // Issuer of DID Token

05  sub: string; // Subject

06  aud: string; // Audience

07  nbf: number; // Not Before Timestamp

08  tid: string; // DID Token ID

09  add: string; // (optional) Misc additional signed data

10}

As a convenience, the above interface is available to your code in TypeScript:

01import { Claim } from '@magic-sdk/admin';

#validate

Validates a Decentralized ID token.

#Arguments

• didToken (String): A Decentralized ID Token generated by a Magic user on the client-side
• attachment? (String): Arbitrary, serialized data to be used for recovery of the add field on the Decentralized ID Token (Defaults to "none")

#Returns

• void: The function will return if the specified DID token is authentic and not expired. If the token is forged or otherwise invalid, the function will throw a descriptive error.

#Users Module

#getMetadataByIssuer

Retrieves information about user by the supplied "issuer".

#Arguments

• issuer (String): The user's Decentralized ID, which can be parsed using TokenModule.getIssuer

#Returns

• A MagicUserMetadata: The data field contains all of the user meta information.
  • issuer (String): The user's Decentralized ID
  • publicAddress (String): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
  • email (String): The user's email address
  • phoneNumber (String | null): The user's phone number
  • oauthProvider (String | null): OAuth provider, if any
  • wallets (Object[]): The multichain wallets of the authenticated user

#getMetadataByPublicAddress

Retrieves information about user by the supplied public address.

#Arguments

• publicAddress (String): The user's Ethereum public address, which can be parsed using TokenModule.getPublicAddress

#Returns

• A MagicUserMetadata: The data field contains all of the user meta information.
  • issuer (String): The user's Decentralized ID
  • publicAddress (String): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
  • email (String): The user's email address
  • phoneNumber (String | null): The user's phone number
  • oauthProvider (String | null): OAuth provider, if any
  • wallets (Object[]): The multichain wallets of the authenticated user

#getMetadataByToken

Retrieves information about user by the supplied DID Token.

#Arguments

• didToken (String): A valid Decentralized ID Token generated client-side by a Magic user

#Returns

• A MagicUserMetadata: The data field contains all of the user meta information.
  • issuer (String): The user's Decentralized ID
  • publicAddress (String): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
  • email (String): The user's email address
  • phoneNumber (String | null): The user's phone number
  • oauthProvider (String | null): OAuth provider, if any
  • wallets (Object[]): The multichain wallets of the authenticated user

#logoutByIssuer

Logs a user out of all client-side Magic SDK sessions given the user's Decentralized ID.

#Arguments

• issuer (String): The user's Decentralized ID, which can be parsed using TokenModule.getIssuer

#Returns

• Promise<void>

#logoutByPublicAddress

Logs a user out of all client-side Magic SDK sessions given the user's public address.

#Arguments

• publicAddress (String): The user's Ethereum public address to log out via the Magic API.

#Returns

• Promise<void>

#logoutByToken

Logs a user out of all client-side Magic SDK sessions given the user's DID token.

#Arguments

• didToken (String): A valid Decentralized ID Token generated client-side by a Magic user

#Returns

• Promise<void>

#Multichain Methods

The following multichain methods require the use of the enum WalletType that is exported from the Magic Admin SDK.

01⁠enum WalletType {

02  ETH = 'ETH',

03  HARMONY = 'HARMONY',

04  ICON = 'ICON',

05  FLOW = 'FLOW',

06  TEZOS = 'TEZOS',

07  ZILLIQA = 'ZILLIQA',

08  POLKADOT = 'POLKADOT',

09  SOLANA = 'SOLANA',

10  AVAX = 'AVAX',

11  ALGOD = 'ALGOD',

12  COSMOS = 'COSMOS',

13  CELO = 'CELO',

14  BITCOIN = 'BITCOIN',

15  NEAR = 'NEAR',

16  HELIUM = 'HELIUM',

17  CONFLUX = 'CONFLUX',

18  TERRA = 'TERRA',

19  TAQUITO = 'TAQUITO',

20  ED = 'ED',

21  HEDERA = 'HEDERA',

22  NONE = 'NONE',

23  ANY = 'ANY',

24}

#getMetadataByIssuerAndWallet

Retrieves information about user, including their multichain wallets, by the supplied issuer.

#Arguments

• issuer (String): The user's Decentralized ID, which can be parsed using TokenModule.getIssuer
• walletType (WalletType): The wallet type. Must import WalletType from Admin SDK.

#Returns

• A MagicUserMetadata: The data field contains all of the user meta information.
  • issuer (String): The user's Decentralized ID
  • publicAddress (String): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
  • email (String): The user's email address
  • phoneNumber (String | null): The user's phone number
  • oauthProvider (String | null): OAuth provider, if any
  • wallets (Object[]): The multichain wallets of the authenticated user

#getMetadataByPublicAddressAndWallet

Retrieves information about user, including their multichain wallets, by the supplied public address.

#Arguments

• publicAddress (String): The user's Ethereum public address, which can be parsed using TokenModule.getPublicAddress
• walletType (WalletType): The wallet type. Must import WalletType from Admin SDK.

#Returns

• A MagicUserMetadata: The data field contains all of the user meta information.
  • issuer (String): The user's Decentralized ID
  • publicAddress (String): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
  • email (String): The user's email address
  • phoneNumber (String | null): The user's phone number
  • oauthProvider (String | null): OAuth provider, if any
  • wallets (Object[]): The multichain wallets of the authenticated user

#getMetadataByTokenAndWallet

Retrieves information about user, including their multichain wallets, by the supplied DID Token.

#Arguments

• didToken (String): A valid Decentralized ID Token generated client-side by a Magic user
• walletType ( WalletType ): The wallet type. Must import WalletType from Admin SDK.

#Returns

• A MagicUseMetadata: The data field contains all of the user meta information.
  • issuer (String): The user's Decentralized ID
  • publicAddress (String): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
  • email (String): The user's email address
  • phoneNumber (String | null): The user's phone number
  • oauthProvider (String | null): OAuth provider, if any
  • wallets (Object[]): The multichain wallets of the authenticated user

#Utils Module

The Utils Module and it's members are accessible on the Magic Admin SDK instance by the utils property.

01const { Magic } = require('@magic-sdk/admin');

02

03const magic = new Magic();

04

05magic.utils;

06magic.utils.parseAuthorizationHeader;

#parseAuthorizationHeader

#Arguments

• header (String): A request authorization header passed in from the client-side application that looks like Bearer WyIweG...n0iXQ==

#Returns

• string: The DID token embedded in the authorization header ⁠ This is only available to Admin SDK version 1.1.0 and above.

#Errors & Warnings

#SDKError

The SDKError class is exposed for instanceof operations.

01import { SDKError } from '@magic-sdk/admin';

02

03try {

04  // Something async...

05catch (err) {

06  if (err instanceof SDKError) {

07    // Handle...

08  }

09}

Additionally, an enumeration of relevant error codes is also exposed for convenience and human readability:

01import { ErrorCode } from '@magic-sdk/admin';

02

03ErrorCode.ApiKeyMissing;

04ErrorCode.MissingAuthHeader;

05ErrorCode.IncorrectSignerAddress;

06// and so forth...

07// Please reference the `Enum Key` column of the error table below.

#Error Codes

#data & Nested Errors

For additional context about an error, the SDKError.data property contains an array of potentially illuminating metadata. At the moment, this property is reserved for service errors when communication to Magic APIs fail.

#Resources

• GitHub
• NPM

#Versions

All changes to the SDK are covered in our latest release notes.