Node API Reference

Node API Reference

#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

NPM
Yarn
01npm install @magic-sdk/admin

#Constructor

#Magic.init()

Parameter

Type

Definition

secretApiKey

String

Your secret API Key retrieved from the Magic Dashboard.

options.endpoint?

String

A URL pointing to the Magic API. You should not need to provide this value except in case you are building highly custom integration tests.

#Initialization

Typescript
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.

Typescript
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

#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:

Typescript
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:

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

note

Only available with Dedicated Wallet.

#getMetadataByIssuer

Retrieves information about user by the supplied "issuer".

#Arguments

#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

#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

#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.

Typescript
01enum 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.

Typescript
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.

Typescript
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:

Typescript
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

Enum KeyDescription
TokenExpiredThe supplied DID Token is invalid due to an expired timestamp.
TokenCannotBeUsedYetThe nbf ("not before") field of the supplied DID Token is set in the future. By default, a 5 minute leeway is added to the timestamp.
IncorrectSignerAddressThe supplied DID Token is invalid due to a mismatch between the signature origin and the claimed user public address.
FailedRecoveryProofThe supplied DID Token could not be recovered using Elliptic Curve recovery.
ApiKeyMissingThe API key required for a particular action is missing or malformed.
MalformedTokenErrorThe supplied DID Token could not be successfully parsed.
ServiceErrorAn error occurred while communicating with the Magic API. Be sure to check the data property of the error object for additional context.

ExpectedBearerString

The supplied DID token needs to be in the proper format of Bearer {token}

AudienceMismatch

Audience does not match client ID. Please ensure your secret key matches the application which generated the DID token.

#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

#Versions

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