Python API Reference

Python API Reference

#Overview

The Magic package for Python is your entry-point to secure, passwordless authentication for your application. This guide will cover some important topics for getting started with Magic Python package 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

Current SDK is built with Python3.6. Testing for Python3.6+ will be added soon.

note

If you are interested in using the SDK with the earlier versions of Python (ex: 2.7+), please create a ticket in this repo and let us know.

PIP
Conda
01pip install magic-admin

#Constructor

#Magic()

Parameter

Type

Definition

api_secret_key

str

Your secret API Key retrieved from the Magic Dashboard.

retries?

num

Total number of retries to allow.

timeout?

num

A period of time the request is going to wait for a response.

backoff_factor?

num

A backoff factor to apply between retry attempts.

#Initialization

Initialize Magic instance.

Python
01from magic_admin import Magic
02
03magic = Magic(
04    api_secret_key='<SECRET_API_KEY>',
05    retries=5,
06    timeout=5,
07    backoff_factor=0.01,
08)

#Token Resource

The token resource and its methods are accessible on the Magic instance by the Token attribute. It provides methods to interact with the DID Token.

note

The token resource does not make any API calls to the Magic server.

Python
01from magic_admin import Magic
02
03magic = Magic(api_secret_key='<SECRET_API_KEY>')
04
05magic.Token
06magic.Token.get_issuer
07magic.Token.get_public_address
08magic.Token.decode
09magic.Token.validate

#get_issuer

Extracts the iss from the DID Token.

Python
01Token.get_issuer(did_token)

#Arguments

  • did_token (str): A DID Token generated by a Magic User on the client-side

#Raises

  • DIDTokenMalformed if the given DID Token is malformed

#Returns

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

#get_public_address

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

Python
01Token.get_public_address(did_token)

#Arguments

  • did_token (str): A DID Token generated by a Magic user on the client-side

#Raises

  • DIDTokenMalformed if the given DID Token is malformed

#Returns

  • A 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.

Python
01Token.decode(did_token)

#Arguments

  • did_token (str): A DID Token generated by a Magic user on the client-side

#Raises

  • DIDTokenMalformed if the given DID Token is malformed

#Returns

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

#validate

Validates a DID token.

Python
01magic.Token.validate(did_token)

#Arguments

  • did_token (str): A DID Token generated by a Magic user on the client-side

#Raises

  • DIDTokenMalformed if the given DID Token is malformed
  • DIDTokenInvalid if the given DID Token is invalid

#Returns

  • None.

#User Resource

The user resource and its methods are accessible on the Magic instance by the User attribute. It provides methods to interact with the User.

Python
01from magic_admin import Magic
02
03magic = Magic(api_secret_key='<SECRET_API_KEY>')
04
05magic.User
06magic.User.get_metadata_by_issuer
07magic.User.get_metadata_by_public_address
08magic.User.get_metadata_by_token
09magic.User.logout_by_issuer
10magic.User.logout_by_public_address
11magic.User.logout_by_token

#get_metadata_by_issuer

Retrieves information about the user by the supplied iss from the DID Token. This method is useful if you store the iss with your user data, which is recommended.

Python
01User.get_metadata_by_issuer(issuer)

#Arguments

  • issuer (str): The user's Decentralized ID, which can be parsed using Token.get_issuer

#Raises

  • RateLimitingError: If you have sent too many requests within a given period of time
  • BadRequestError: If the supplied parameters are invalid
  • AuthenticationError: If your API secret key cannot be authenticated with Magic API server
  • ForbiddenError: If your API secret key is not authorized to access the resources
  • APIError: For any other API error
  • APIConnectionError: If your server cannot communicate with the Magic server. Normally this is a network communication error.
note

See Error Handling for more examples.

#Returns

  • A MagicResponse: The data field contains all of the user meta information.
    • issuer (str): The user's Decentralized ID
    • public_address (str): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
    • email (str): The user's email address
    • phone_number (str): The user's phone number
    • oauth_provider (str): OAuth provider, if any
    • wallets (arr): Array of user's wallet addresses

#get_metadata_by_public_address

Retrieves information about the user by the supplied public_address. This method is useful if you store the public_address with your user data.

Python
01User.get_metadata_by_public_address(public_address)

#Arguments

#Raises

  • RateLimitingError: If you have sent too many requests within a given period of time.
  • BadRequestError: If the supplied parameters are invalid
  • AuthenticationError: If your API secret key cannot be authenticated with Magic API server
  • ForbiddenError: If your API secret key is not authorized to access the resources
  • APIError: For any other API error
  • APIConnectionError: If your server cannot communicate with the Magic server. Normally this is a network communication error.
note

See Error Handling for more examples.

#Returns

  • A MagicResponse: The data field contains all of the user meta information.
    • issuer (str): The user's Decentralized ID
    • public_address (str): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
    • email (str): The user's email address
    • phone_number (str): The user's phone number
    • oauth_provider (str): OAuth provider, if any
    • wallets (arr): Array of user's wallet addresses

#get_metadata_by_token

Retrieves information about the user by the supplied DID Token.

Python
01User.get_metadata_by_token(did_token)

#Arguments

  • did_token (str): A DID Token generated by a Magic User on the client-side.

#Raises

  • RateLimitingError: If you have sent too many requests within a given period of time
  • BadRequestError: If the supplied parameters are invalid
  • AuthenticationError: If your API secret key cannot be authenticated with Magic API server
  • ForbiddenError: If your API secret key is not authorized to access the resources
  • APIError: For any other API error
  • APIConnectionError: If your server cannot communicate with the Magic server. Normally this is a network communication error.
note

See Error Handling for more examples.

#Returns

  • A MagicResponse: The data field contains all of the user meta information.
    • issuer (str): The user's Decentralized ID
    • public_address (str): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
    • email (str): The user's email address
    • phone_number (str): The user's phone number
    • oauth_provider (str): OAuth provider, if any
    • wallets (arr): Array of user's wallet addresses

#logout_by_issuer

Logs a user out of all Magic SDK sessions given the user's Decentralized ID (iss). This method is useful if you store the iss with your user data, which is recommended.

Python
01User.logout_by_issuer(issuer)

#Arguments

  • issuer (str): The user's Decentralized ID, which can be parsed using Token.get_issuer

#Raises

  • RateLimitingError: If you have sent too many requests within a given period of time
  • BadRequestError: If the supplied parameters are invalid
  • AuthenticationError: If your API secret key cannot be authenticated with Magic API server
  • ForbiddenError: If your API secret key is not authorized to access the resources
  • APIError: For any other API error
  • APIConnectionError: If your server cannot communicate with the Magic server. Normally this is a network communication error.
note

See Error Handling for more examples.

#Returns

#logout_by_public_address

Logs a user out of all Magic SDK sessions given the user's public address. This method is useful if you store the public_address.

Python
01User.logout_by_public_address(public_address)

#Arguments

  • public_address (str): The user's Ethereum public address

#Raises

  • RateLimitingError: If you have sent too many requests within a given period of time
  • BadRequestError: If the supplied parameters are invalid
  • AuthenticationError: If your API secret key cannot be authenticated with Magic API server
  • ForbiddenError: If your API secret key is not authorized to access the resources
  • APIError: For any other API error
  • APIConnectionError: If your server cannot communicate with the Magic server. Normally this is a network communication error.
note

See Error Handling for more examples.

#Returns

#logout_by_token

Logs a user out of all Magic SDK sessions given the DID Token.

Python
01User.logout_by_token(did_token)

#Arguments

  • did_token (str): A DID Token generated by a Magic user on the client-side

#Raises

  • RateLimitingError: If you have sent too many requests within a given period of time
  • BadRequestError: If the supplied parameters are invalid
  • AuthenticationError: If your API secret key cannot be authenticated with Magic API server
  • ForbiddenError: If your API secret key is not authorized to access the resources
  • APIError: For any other API error
  • APIConnectionError: If your server cannot communicate with the Magic server. Normally this is a network communication error.
note

See Error Handling for more examples.

#Returns

#Response and Error Handling

#Response

There is only one response object that will be returned from a successful API call.

#MagicResponse

This is the interface to interact Magic API responses. It will only be returned if the API request status code is between 200 (inclusive) and 300 (exclusive).

You will have access to the following attributes:

  • content (bytes): Raw content returned by the API response
  • status_code (num): HTTP status code for the given request
  • data (dict): Parsed content
Python
01from magic_admin.response import MagicResponse
02
03MagicResponse.content
04MagicResponse.status
05MagicResponse.data

#Errors

The conventional HTTP response is adopted by the SDK. For the status code in:

  • 2XX - Indicates success
  • 4XX - Indicates client errors. Information provided to the SDK is invalid.
  • 5XX - Indicates server errors

Below is the error class inheritance which can help developers to programmatically handle the error cases.

01MagicError
02    |
03    |------- RequestError
04                  |
05                  | ------- RateLimitingError
06                  | ------- BadRequestError
07                  | ------- AuthenticationError
08                  | ------- ForbiddenError
09                  | ------- APIError
10                  | ------- APIConnectionError
11   |
12   | ------- DIDTokenInvalid
13   |
14   | ------- DIDTokenMalformed
15   |
16   | ------- DIDTokenExpired

#MagicError

This is the base class of all the Magic SDK errors.

Python
01MagicError(message=None)

#RequestError

This is the base class of all the Magic API request errors. This error class will provide details of unsuccessful API requests.

Python
01RequestError(
02    message=None, http_status=None, http_code=None, http_resp_data=None,
03    http_message=None, http_error_code=None, http_request_params=None,
04    http_request_data=None, http_method=None,
05)
CodeErrorDescription
429RateLimitingErrorToo many requests are submitted for a given period of time.
400BadRequestErrorThe API requests might have missing required fields or bad inputs.
401AuthenticationErrorThis means your API secret key is invalid.
403ForbiddenErrorThis normally means the given API secret key doesn't have permission to perform the action on the given resources.
APIErrorThis is a generic API error that handles other status codes that are not explicitly handled. Ex: 500 , 404 , etc.
APIConnectionErrorNetwork connection error. This normally means the connection between between your application and Magic API server cannot be established.

#DIDTokenInvalid

This means the given token fails the validation.

#DIDTokenMalformed

This means the given token format is invalid.

#DIDTokenExpired

This means the given token has expired.

#Error Handling

It is recommended to implement error handling for API responses.

Python
01try:
02    # Make requests to Magic server.
03except RateLimitingError as e:
04    pass
05except BadRequestError as e:
06    pass
07except AuthenticationError as e:
08    pass
09except ForbiddenError as e:
10    pass
11except APIError as e:
12    pass
13except APIConnectionError as e:
14    pass
15except DIDTokenInvalid as e:
16    pass
17except DIDTokenMalformed as e:
18    pass
19except DIDTokenExpired as e:
20    pass

#Resources

#Versions

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