Ruby API Reference
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.
Magic.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
require 'magic-admin'
magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>',
retries: 5,
timeout: 5,
backoff: 0.01)
# Or add environment variables
# `MAGIC_API_SECRET_KEY`
# `MAGIC_API_RETRIES`
# `MAGIC_API_TIMEOUT`
# `MAGIC_API_BACKOFF`
magic = 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.
The token resource does not make any API calls to the Magic server.
require 'magic-admin'
magic = Magic.new(api_secret_key: 'sk_live_...')
magic.token
magic.token.get_issuer
magic.token.get_public_address
magic.token.decode
magic.token.validate
#get_issuer
Extracts the iss
from the DID Token.
token.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.
#Example
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.
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_issuer_service'
# Using
MagicIssuerService.call(headers)
# Definition
class MagicIssuerService
def self.call(headers)
new(headers).get_issuer
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def get_issuer
begin
validate_did_token?
magic.token.get_issuer(did_token)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#get_public_address
Gets the cryptographic public address of the Magic User who generated the supplied DID Token.
token.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
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.
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_public_address_service'
# Using
MagicPublicAddressService.call(headers)
# Definition
class MagicPublicAddressService
def self.call(headers)
new(headers).get_public_address
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def get_public_address
begin
validate_did_token?
magic.token.get_public_address(did_token)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#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.
Token.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 givenclaim
claim
(dict): Unsigned data the user asserts. This should equal theproof
after Elliptic Curve recovery. See Decentralized ID Token Specification for fields inside theclaim
.
#Example
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_proof_claim_service'
# Using
proof, claim = MagicProofClaimService.call(headers)
# Definition
class MagicProofClaimService
def self.call(headers)
new(headers).get_proof_claim
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def get_proof_claim
begin
validate_did_token?
magic.token.decode(did_token)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#validate
Validates a DID token.
token.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
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.
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_validate_service'
# Using
MagicValidateService.call(headers)
# Definition
class MagicValidateService
def self.call(headers)
new(headers).validate
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def validate
begin
validate_did_token?
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#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.
require 'magic-admin'
magic = Magic.new(api_secret_key: 'sk_live_...')
magic.user
magic.user.get_metadata_by_issuer
magic.user.get_metadata_by_public_address
magic.user.get_metadata_by_token
magic.user.logout_by_issuer
magic.user.logout_by_public_address
magic.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.
user.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.
See Error Handling for more examples.
#Returns
- A
MagicResponse
: Thedata
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
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.
require 'magic-admin'
require 'magic_user_metadata_service'
# Using
MagicUserMetadataService.call(headers)
# Definition
class MagicUserMetadataService
def self.call(headers)
new(headers).get_metadata
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def get_metadata
begin
validate_did_token?
magic.user.get_metadata_by_issuer(issuer)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
rescue MagicAdmin::RequestError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def issuer
magic.token.get_issuer(did_token)
end
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#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.
user.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.
See Error Handling for more examples.
#Returns
- A
MagicResponse
: Thedata
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
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.
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_user_metadata_service'
# Using
MagicUserMetadataService.call(headers)
# Definition
class MagicUserMetadataService
def self.call(headers)
new(headers).get_metadata
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def get_metadata
begin
validate_did_token?
magic.user.get_metadata_by_public_address(public_address)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
rescue MagicAdmin::RequestError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def public_address
magic.token.get_public_address(did_token)
end
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#get_metadata_by_token
Retrieves information about the user by the supplied DID Token.
user.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.
See Error Handling for more examples.
#Returns
- A
MagicResponse
: Thedata
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
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.
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_user_metadata_service'
# Using
MagicUserMetadataService.call(headers)
# Definition
class MagicUserMetadataService
def self.call(headers)
new(headers).get_metadata
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def get_metadata
begin
validate_did_token?
magic.user.get_metadata_by_token(did_token)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
rescue MagicAdmin::RequestError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#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.
user.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.
See Error Handling for more examples.
#Returns
#Example
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.
require 'magic-admin'
require 'magic_user_logout_service'
# Using
MagicUserLogoutService.call(headers)
# Definition
class MagicUserLogoutService
def self.call(headers)
new(headers).logout
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def logout
begin
validate_did_token?
magic.user.logout_by_issuer(issuer)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
rescue MagicAdmin::RequestError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def issuer
magic.token.get_issuer(did_token)
end
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#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
.
user.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.
See Error Handling for more examples.
#Returns
#Example
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.
require 'magic-admin'
require 'magic_user_logout_service'
# Using
MagicUserLogoutService.call(headers)
# Definition
class MagicUserLogoutService
def self.call(headers)
new(headers).logout
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def logout
begin
validate_did_token?
magic.user.logout_by_public_address(public_address)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
rescue MagicAdmin::RequestError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def public_address
magic.token.get_public_address(did_token)
end
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#logout_by_token
Logs a user out of all Magic SDK sessions given the DID Token.
user.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.
See Error Handling for more examples.
#Returns
#Example
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.
It is important to always validate the DID Token before using.
require 'magic-admin'
require 'magic_user_logout_service'
# Using
MagicUserLogoutService.call(headers)
# Definition
class MagicUserLogoutService
def self.call(headers)
new(headers).logout
end
def initialize(headers = {})
@headers = headers
@magic = Magic.new(api_secret_key: '<YOUR_API_SECRET_KEY>')
end
def logout
begin
validate_did_token?
magic.user.logout_by_token(did_token)
rescue MagicAdmin::DIDTokenError => e
e.message
# Your rescue code
rescue MagicAdmin::RequestError => e
e.message
# Your rescue code
end
end
private
attr_reader :headers, :magic
def validate_did_token?
magic.token.validate(did_token)
end
def did_token
return nil if headers['Authorization'].nil?
headers['Authorization'].split(' ').last
end
end
#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.
require 'magic-admin'
response = MagicAdmin::Http::Response.new(http_resp)
response.content
response.data
response.status_code
#Errors
The conventional HTTP response is adopted by the SDK. For the status code in :
2XX
- Indicates success4XX
- 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.
MagicError
|
|------- DIDTokenError
|
|------- RequestError
|
|------- RateLimitingError
|------- BadRequestError
|------- AuthenticationError
|------- ForbiddenError
|------- APIError
|------- APIConnectionError
#MagicError
This is the base class of all the Magic SDK errors.
MagicError.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.
http_detail = {
http_status: '<http_status>',
http_code: '<http_code>',
http_response: '<http_response>',
http_message: '<http_message>',
http_error_code: '<http_error_code>',
http_request_params: '<http_request_params>',
http_request_data: '<http_request_data>',
http_method: '<http_method>'
}
MagicAdmin::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.
begin
# Make requests to Magic server.
rescue MagicAdmin::DIDTokenError => e
puts e.message
rescue MagicAdmin::RateLimitingError => e
puts e.message
rescue MagicAdmin::BadRequestError => e
puts e.message
rescue MagicAdmin::AuthenticationError => e
puts e.message
rescue MagicAdmin::ForbiddenError => e
puts e.message
rescue MagicAdmin::APIError => e
puts e.message
rescue MagicAdmin::APIConnectionError => e
puts e.message
end