Ruby API Reference

#Constructor

#Magic

The constructor allows you to specify your own API secret key and HTTP request strategy when your application is interacting with the Magic API.

Ruby

01Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>', retries: 5, timeout: 10, backoff: 0.03)

#Arguments

api_secret_key(str): Your API secret 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.

#Returns

A Magic object that provides access to all the supported resources.

#Examples

Ruby

01require 'magic-admin'

03magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>',

04        retries: 5,

05        timeout: 5,

06        backoff: 0.01)

08# Or add environment variables

09# `MAGIC_API_SECRET_KEY`

10# `MAGIC_API_RETRIES`

11# `MAGIC_API_TIMEOUT`

12# `MAGIC_API_BACKOFF`

14magic = Magic.new

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

Ruby

01require 'magic-admin'

03magic = Magic.new(api_secret_key: 'sk_live_...')

04magic.token

05magic.token.get_issuer

06magic.token.get_public_address

07magic.token.decode

08magic.token.validate

#`get_issuer`

Extracts the iss from the DID Token.

Ruby

01token.get_issuer(did_token)

#Arguments

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

#Raises

DIDTokenError if the given DID Token is malformed.

#Returns

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

The example below is assuming you are already using a Ruby Web Framework (Rails, Sinatra, etc.) Web framework's specific imports are omitted in favor of the simplicity of the example. Only the magic_admin related imports are shown below.

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_issuer_service'

04# Using

06MagicIssuerService.call(headers)

08# Definition

09class MagicIssuerService

10  def self.call(headers)

11    new(headers).get_issuer

12  end

14  def initialize(headers = {})

15    @headers = headers

16    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

17  end

19  def get_issuer

20    begin

21      validate_did_token?

22      magic.token.get_issuer(did_token)

23    rescue MagicAdmin::DIDTokenError => e

24      e.message

25      # Your rescue code

26    end

27  end

29  private

31  attr_reader :headers, :magic

33  def validate_did_token?

34    magic.token.validate(did_token)

35  end

37  def did_token

38    return nil if headers['Authorization'].nil?

40    headers['Authorization'].split(' ').last

41  end

42end

#`get_public_address`

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

Ruby

01token.get_public_address(did_token)

#Arguments

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

#Raises

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

#Example

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_public_address_service'

04# Using

05MagicPublicAddressService.call(headers)

07# Definition

08class MagicPublicAddressService

09  def self.call(headers)

10    new(headers).get_public_address

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def get_public_address

19    begin

20      validate_did_token?

21      magic.token.get_public_address(did_token)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    end

26  end

28  private

30  attr_reader :headers, :magic

32  def validate_did_token?

33    magic.token.validate(did_token)

34  end

36  def did_token

37    return nil if headers['Authorization'].nil?

39    headers['Authorization'].split(' ').last

40  end

41end

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

01Token.decode(did_token)

#Arguments

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

#Raises

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

#Example

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_proof_claim_service'

04# Using

05proof, claim = MagicProofClaimService.call(headers)

07# Definition

08class MagicProofClaimService

09  def self.call(headers)

10    new(headers).get_proof_claim

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def get_proof_claim

19    begin

20      validate_did_token?

21      magic.token.decode(did_token)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    end

26  end

28  private

30  attr_reader :headers, :magic

32  def validate_did_token?

33    magic.token.validate(did_token)

34  end

36  def did_token

37    return nil if headers['Authorization'].nil?

39    headers['Authorization'].split(' ').last

40  end

41end

#`validate`

Validates a DID token.

01token.validate(did_token)

#Arguments

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

#Raises

DIDTokenError if the given DID Token is invalid or malformed.

#Returns

None

#Example

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_validate_service'

04# Using

05MagicValidateService.call(headers)

07# Definition

08class MagicValidateService

09  def self.call(headers)

10    new(headers).validate

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def validate

19    begin

20      validate_did_token?

21    rescue MagicAdmin::DIDTokenError => e

22      e.message

23      # Your rescue code

24    end

25  end

27  private

29  attr_reader :headers, :magic

31  def validate_did_token?

32    magic.token.validate(did_token)

33  end

35  def did_token

36    return nil if headers['Authorization'].nil?

38    headers['Authorization'].split(' ').last

39  end

40end

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

Ruby

01require 'magic-admin'

03magic = Magic.new(api_secret_key: 'sk_live_...')

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.

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.
email (str): The user's email address.
public_address (str): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.

#Example

Ruby

01require 'magic-admin'

02require 'magic_user_metadata_service'

04# Using

05MagicUserMetadataService.call(headers)

07# Definition

08class MagicUserMetadataService

09  def self.call(headers)

10    new(headers).get_metadata

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def get_metadata

19    begin

20      validate_did_token?

21      magic.user.get_metadata_by_issuer(issuer)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    rescue MagicAdmin::RequestError => e

26      e.message

27      # Your rescue code

28    end

29  end

31  private

33  attr_reader :headers, :magic

35  def issuer

36    magic.token.get_issuer(did_token)

37  end

39  def validate_did_token?

40    magic.token.validate(did_token)

41  end

43  def did_token

44    return nil if headers['Authorization'].nil?

46    headers['Authorization'].split(' ').last

47  end

48end

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

01user.get_metadata_by_public_address(public_address)

#Arguments

public_address (str): The user's Ethereum public address, which can be parsed using token.get_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

A MagicResponse: The data field contains all of the user meta information.
issuer (str): The user's Decentralized ID.
email (str): The user's email address.
public_address (str): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.

#Example

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_user_metadata_service'

04# Using

05MagicUserMetadataService.call(headers)

07# Definition

08class MagicUserMetadataService

09  def self.call(headers)

10    new(headers).get_metadata

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def get_metadata

19    begin

20      validate_did_token?

21      magic.user.get_metadata_by_public_address(public_address)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    rescue MagicAdmin::RequestError => e

26      e.message

27      # Your rescue code

28    end

29  end

31  private

33  attr_reader :headers, :magic

35  def public_address

36    magic.token.get_public_address(did_token)

37  end

39  def validate_did_token?

40    magic.token.validate(did_token)

41  end

43  def did_token

44    return nil if headers['Authorization'].nil?

46    headers['Authorization'].split(' ').last

47  end

48end

#`get_metadata_by_token`

Retrieves information about the user by the supplied DID Token.

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.
email (str): The user's email address.
public_address (str): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.

#Example

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_user_metadata_service'

04# Using

05MagicUserMetadataService.call(headers)

07# Definition

08class MagicUserMetadataService

09  def self.call(headers)

10    new(headers).get_metadata

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def get_metadata

19    begin

20      validate_did_token?

21      magic.user.get_metadata_by_token(did_token)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    rescue MagicAdmin::RequestError => e

26      e.message

27      # Your rescue code

28    end

29  end

31  private

33  attr_reader :headers, :magic

35  def validate_did_token?

36    magic.token.validate(did_token)

37  end

39  def did_token

40    return nil if headers['Authorization'].nil?

42    headers['Authorization'].split(' ').last

43  end

44end

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

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

A MagicResponse.

#Example

Ruby

01require 'magic-admin'

02require 'magic_user_logout_service'

04# Using

05MagicUserLogoutService.call(headers)

07# Definition

08class MagicUserLogoutService

09  def self.call(headers)

10    new(headers).logout

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def logout

19    begin

20      validate_did_token?

21      magic.user.logout_by_issuer(issuer)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    rescue MagicAdmin::RequestError => e

26      e.message

27      # Your rescue code

28    end

29  end

31  private

33  attr_reader :headers, :magic

35  def issuer

36    magic.token.get_issuer(did_token)

37  end

39  def validate_did_token?

40    magic.token.validate(did_token)

41  end

43  def did_token

44    return nil if headers['Authorization'].nil?

46    headers['Authorization'].split(' ').last

47  end

48end

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

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

A MagicResponse.

#Example

Ruby

01require 'magic-admin'

02require 'magic_user_logout_service'

04# Using

05MagicUserLogoutService.call(headers)

07# Definition

08class MagicUserLogoutService

09  def self.call(headers)

10    new(headers).logout

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def logout

19    begin

20      validate_did_token?

21      magic.user.logout_by_public_address(public_address)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    rescue MagicAdmin::RequestError => e

26      e.message

27      # Your rescue code

28    end

29  end

31  private

33  attr_reader :headers, :magic

35  def public_address

36    magic.token.get_public_address(did_token)

37  end

39  def validate_did_token?

40    magic.token.validate(did_token)

41  end

43  def did_token

44    return nil if headers['Authorization'].nil?

46    headers['Authorization'].split(' ').last

47  end

48end

#`logout_by_token`

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

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

A MagicResponse.

#Example

important

It is important to always validate the DID Token before using.

Ruby

01require 'magic-admin'

02require 'magic_user_logout_service'

04# Using

05MagicUserLogoutService.call(headers)

07# Definition

08class MagicUserLogoutService

09  def self.call(headers)

10    new(headers).logout

11  end

13  def initialize(headers = {})

14    @headers = headers

15    @magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')

16  end

18  def logout

19    begin

20      validate_did_token?

21      magic.user.logout_by_token(did_token)

22    rescue MagicAdmin::DIDTokenError => e

23      e.message

24      # Your rescue code

25    rescue MagicAdmin::RequestError => e

26      e.message

27      # Your rescue code

28    end

29  end

31  private

33  attr_reader :headers, :magic

35  def validate_did_token?

36    magic.token.validate(did_token)

37  end

39  def did_token

40    return nil if headers['Authorization'].nil?

42    headers['Authorization'].split(' ').last

43  end

44end

#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 (string): Raw content returned by the API response.
data (hash): Parsed content.
status_code (num): HTTP status code for the given request.

Ruby

01require 'magic-admin'

03response = MagicAdmin::Http::Response.new(http_resp)

04response.content

05response.data

06response.status_code

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

04    |

05    |------- RequestError

06                  |

07                  |------- RateLimitingError

08                  |------- BadRequestError

09                  |------- AuthenticationError

10                  |------- ForbiddenError

11                  |------- APIError

12                  |------- APIConnectionError

#MagicError

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

Ruby

01MagicError.new('<message>')

#DIDTokenError

Any DID Token related error. This can mean the given token is malformed or invalid.

#RequestError

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

Ruby

01http_detail = {

02   http_status: '<http_status>',

03   http_code: '<http_code>',

04   http_response: '<http_response>',

05   http_message: '<http_message>',

06   http_error_code: '<http_error_code>',

07   http_request_params: '<http_request_params>',

08   http_request_data: '<http_request_data>',

09   http_method: '<http_method>'

10}

11MagicAdmin::RequestError.new('<message>', http_detail)

Code	Error	Description
429	RateLimitingError	Too many requests are submitted for a given period of time.
400	BadRequestError	The API requests might have missing required fields or bad inputs.
401	AuthenticationError	This means your API secret key is invalid.
403	ForbiddenError	This normally means the given API secret key doesn't have permission to perform the action on the given resources.
–	APIError	This is a generic API error that handlers other status codes that are not explicitly handled. Ex: `500` , `404` , etc.
–	APIConnectionError	Network connection error. This normally means the connection between your application and Magic API server cannot be established.

#Error Handling

It is recommended to handle the API errors gracefully.

Ruby

01begin

02   # Make requests to Magic server.

03rescue MagicAdmin::DIDTokenError => e

04   puts e.message

05rescue MagicAdmin::RateLimitingError => e

06   puts e.message

07rescue MagicAdmin::BadRequestError => e

08   puts e.message

09rescue MagicAdmin::AuthenticationError => e

10   puts e.message

11rescue MagicAdmin::ForbiddenError => e

12   puts e.message

13rescue MagicAdmin::APIError => e

14   puts e.message

15rescue MagicAdmin::APIConnectionError => e

16   puts e.message

17end

Ruby API Reference

Ruby API Reference

Product

Developers

Resources

Company

Social

Product

Developers

Resources

Company

Social

Product

Developers

Resources

Company

Social