​
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

The Magic Admin Node SDK requires Node.js 18 or higher. 
npm install @magic-sdk/admin

​
Constructor

Magic.init()
ParameterTypeDefinition
secretApiKeyStringYour secret API Key retrieved from the Magic Dashboard.
options.endpoint?StringA URL pointing to the Magic API. You should not need to provide this value except in case you are building highly custom integration tests.
options.clientId?StringYour Magic client ID. If not provided, will be fetched automatically.

​
Initialization

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

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

​
Token Module

The Token Module and its members are accessible on the Magic Admin SDK instance by the token property.
The token module does not make any API calls to the Magic server.

​
getIssuer

Extracts the iss from the DID Token.
Node.js
magic.token.getIssuer(didToken)
Arguments Throws
  • MalformedTokenError: If the given DID Token is malformed
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 DID Token.
Node.js
magic.token.getPublicAddress(didToken)
Arguments
  • didToken (String): A Decentralized ID Token generated by a Magic user on the client-side
Throws
  • MalformedTokenError: If the given DID Token is malformed
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 DID Token from a Base64 string into a tuple of its individual components: proof and claim. This method allows you decode the DID Token and inspect the token. You can apply your own rules and validations on top of the current Token.validate method.
Node.js
magic.token.decode(didToken)
Arguments
  • didToken (String): A Decentralized ID Token generated by a Magic user on the client-side
Throws
  • MalformedTokenError: If the given DID Token is malformed
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:
Node.js
interface Claim {
  iat: number; // Issued At Timestamp
  ext: number; // Expiration Timestamp
  iss: string; // Issuer of DID Token
  sub: string; // Subject
  aud: string; // Audience
  nbf: number; // Not Before Timestamp
  tid: string; // DID Token ID
  add: string; // (optional) Misc additional signed data
}
As a convenience, the above interface is available to your code in TypeScript:
Node.js
import { Claim } from '@magic-sdk/admin';

​
validate

Validates a DID token.
Node.js
await magic.token.validate(didToken)
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")
Throws
  • MalformedTokenError: If the given DID Token is malformed
  • TokenExpired: If the given DID Token has expired
  • IncorrectSignerAddress: If the given DID Token is invalid
Returns
  • Promise<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 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. Supported Networks
  • EVM Compatible: ETH, AVAX, CELO, HARMONY, ICON, ZILLIQA, HEDERA, CONFLUX, TERRA, TAQUITO, ED
  • Non-EVM: SOLANA, POLKADOT, NEAR, FLOW, TEZOS, COSMOS, ALGOD, BITCOIN, HELIUM

​
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 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
Example
Node.js
const { Magic, WalletType } = require('@magic-sdk/admin');

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

// Get user metadata for Solana wallet
const response = await magic.users.getMetadataByTokenAndWallet(
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ...",
  WalletType.SOLANA
);

console.log(`Solana wallet address: ${response.data.publicAddress}`);

​
Utils Module

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

​
parseAuthorizationHeader

Extracts a DID token from an HTTP Authorization header. 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
Example
Node.js
const { Magic } = require('@magic-sdk/admin');

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

// Extract token from Authorization header
const authHeader = "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ...";
const didToken = magic.utils.parseAuthorizationHeader(authHeader);

​
validateTokenOwnership

Validates that a user owns a specific NFT token for token gating functionality. Arguments
  • didToken (String): The DID token to validate
  • contractAddress (String): The smart contract address of the NFT
  • contractType (String): Either 'ERC721' or 'ERC1155'
  • rpcURL (String): The RPC endpoint URL for the blockchain
  • tokenId (String, optional): Required for ERC1155 contracts
Returns
  • Promise<Object>: Response with validation result
    • valid (Boolean): Whether the user owns the token
    • error_code (String): Error code if validation fails
    • message (String): Human-readable error message
Example
Node.js
const { Magic } = require('@magic-sdk/admin');

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

// Validate ERC721 token ownership
const result = await magic.utils.validateTokenOwnership(
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ...",
  "0x1234567890123456789012345678901234567890",
  "ERC721",
  "https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
);

if (result.valid) {
  console.log("User owns the NFT!");
} else {
  console.log(`Validation failed: ${result.message}`);
}

​
Errors & Warnings

​
SDKError

The SDKError class is exposed for instanceof operations and provides structured error handling.
Node.js
const { Magic, SDKError, ErrorCode } = require('@magic-sdk/admin');

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

try {
  // Validate a DID token
  await magic.token.validate(didToken);
  console.log("Token is valid!");
  
  // Get user metadata
  const userData = await magic.users.getMetadataByToken(didToken);
  console.log(`User email: ${userData.data.email}`);
  
} catch (err) {
  if (err instanceof SDKError) {
    switch (err.code) {
      case ErrorCode.TokenExpired:
        console.log("Token has expired, please login again");
        break;
      case ErrorCode.MalformedTokenError:
        console.log("Invalid token format");
        break;
      case ErrorCode.IncorrectSignerAddress:
        console.log("Token signature verification failed");
        break;
      case ErrorCode.ApiKeyMissing:
        console.log("API key is missing or invalid");
        break;
      default:
        console.log(`SDK Error: ${err.message}`);
    }
  } else {
    console.log(`Unexpected error: ${err.message}`);
  }
}

​
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.
ExpectedBearerStringThe supplied DID token needs to be in the proper format of Bearer {token}
AudienceMismatchAudience 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