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');

03let magic;

05// Construct with an API key:

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

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');

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

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:

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

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.

Typescript

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.

Typescript

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

03const magic = new Magic();

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';

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';

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 Key	Description
`TokenExpired`	The supplied DID Token is invalid due to an expired timestamp.
`TokenCannotBeUsedYet`	The `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.
`IncorrectSignerAddress`	The supplied DID Token is invalid due to a mismatch between the signature origin and the claimed user public address.
`FailedRecoveryProof`	The supplied DID Token could not be recovered using Elliptic Curve recovery.
`ApiKeyMissing`	The API key required for a particular action is missing or malformed.
`MalformedTokenError`	The supplied DID Token could not be successfully parsed.
`ServiceError`	An 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.

Node API Reference

Node API Reference

Laravel API Reference

Go API Reference

About

Developers

Resources

Social

About

Developers

Resources

Social

About

Developers

Resources

Social