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
01npm install @magic-sdk/admin
#Constructor
#Magic.init()
Parameter | Type | Definition |
| String | Your secret API Key retrieved from the Magic Dashboard. |
| 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
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 givenclaim
claim
(Object): Unsigned data the user asserts. This should equal theproof
after Elliptic Curve recovery. See Decentralized ID Token Specification for fields inside theclaim
.
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-sideattachment?
(String): Arbitrary, serialized data to be used for recovery of theadd
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
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 usingTokenModule.getIssuer
#Returns
- A
MagicUserMetadata
: Thedata
field contains all of the user meta information.issuer
(String): The user's Decentralized IDpublicAddress
(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 addressphoneNumber
(String | null): The user's phone numberoauthProvider
(String | null): OAuth provider, if anywallets
(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 usingTokenModule.getPublicAddress
#Returns
- A
MagicUserMetadata
: Thedata
field contains all of the user meta information.issuer
(String): The user's Decentralized IDpublicAddress
(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 addressphoneNumber
(String | null): The user's phone numberoauthProvider
(String | null): OAuth provider, if anywallets
(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
: Thedata
field contains all of the user meta information.issuer
(String): The user's Decentralized IDpublicAddress
(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 addressphoneNumber
(String | null): The user's phone numberoauthProvider
(String | null): OAuth provider, if anywallets
(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 usingTokenModule.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.
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 usingTokenModule.getIssuer
walletType
(WalletType): The wallet type. Must importWalletType
from Admin SDK.
#Returns
- A
MagicUserMetadata
: Thedata
field contains all of the user meta information.issuer
(String): The user's Decentralized IDpublicAddress
(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 addressphoneNumber
(String | null): The user's phone numberoauthProvider
(String | null): OAuth provider, if anywallets
(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 usingTokenModule.getPublicAddress
walletType
(WalletType): The wallet type. Must importWalletType
from Admin SDK.
#Returns
- A
MagicUserMetadata
: Thedata
field contains all of the user meta information.issuer
(String): The user's Decentralized IDpublicAddress
(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 addressphoneNumber
(String | null): The user's phone numberoauthProvider
(String | null): OAuth provider, if anywallets
(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 userwalletType
( WalletType ): The wallet type. Must importWalletType
from Admin SDK.
#Returns
- A
MagicUseMetadata
: Thedata
field contains all of the user meta information.issuer
(String): The user's Decentralized IDpublicAddress
(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 addressphoneNumber
(String | null): The user's phone numberoauthProvider
(String | null): OAuth provider, if anywallets
(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 likeBearer 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
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. |
| The supplied DID token needs to be in the proper format of |
| 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.