home
connect
auth

PHP API Reference

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

PHP
01$magic = new \MagicAdmin\Magic('<API_SECRET_KEY>', <RETRIES>, <TIMEOUT>, <BACKOFF_FACTOR>);

#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

PHP
01$magic = new \MagicAdmin\Magic(
02    '<YOUR_API_SECRET_KEY>'
03    5,
04    5,
05    0.01,
06);

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

PHP
01$magic = new \MagicAdmin\Magic('sk_live_...');
02

03$magic->token
04$magic->token->get_issuer
05$magic->token->get_public_address
06$magic->token->decode
07$magic->token->validate

#get_issuer

Extracts the iss from the DID Token.

PHP
01token.get_issuer(did_token)

#Arguments

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

#Raises

DIDTokenException if the given DID Token is malformed.

#Returns

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

#Example

important

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

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16    $issuer = $magic->token->get_issuer($did_token);
17  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
18    // DIDT is malformed. You can handle this by remapping it to your application
19    // error.
20  }

#get_public_address

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

PHP
01token.get_public_address(did_token)

#Arguments

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

#Raises

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

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16    $public_address = $magic->token->get_public_address($did_token);
17  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
18    // DIDT is malformed. You can handle this by remapping it to your application
19    // error.
20  }

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

PHP
01token.decode(did_token)

#Arguments

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

#Raises

DIDTokenException if the given DID Token is malformed.

#Returns

  • proof (str): A digital signature that proves the validity of the given claim
  • claim (array): 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.

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16    list($proof , $claim) = $magic->token->decode($did_token);
17  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
18    // DIDT is malformed. You can handle this by remapping it to your application
19    // error.
20  }

#validate

Validates a DID token.

PHP
01token.validate(did_token)

#Arguments

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

#Raises

DIDTokenException if the given DID Token is invalid or malformed.

#Returns

None

#Example

important

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

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
17    // DIDT is malformed. You can handle this by remapping it to your application
18    // error.
19  }

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

PHP
01$magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
02

03$magic->user
04$magic->user->get_metadata_by_issuer
05$magic->user->get_metadata_by_public_address
06$magic->user->get_metadata_by_token
07$magic->user->logout_by_issuer
08$magic->user->logout_by_public_address
09$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.

PHP
01user.get_metadata_by_issuer(issuer)

#Arguments

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

#Raises

  • RateLimitingException: If you have sent too many requests within a given period of time.
  • BadRequestException: If the supplied parameters are invalid.
  • AuthenticationException: If your API secret key cannot be authenticated with Magic API server.
  • ForbiddenException: If your API secret key is not authorized to access the resources.
  • ApiException: For any other API error.
  • ApiConnectionException: 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

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16    $issuer = $magic->token->get_issuer($did_token);
17    $user_meta = $magic->user->get_metadata_by_issuer($issuer);
18  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
19    // DIDT is malformed. You can handle this by remapping it to your application
20    // error.
21  } catch (\MagicAdmin\Exception\RequestException $e) {
22    // HTTP error. You can handle this by remapping it to your application error.
23  }

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

PHP
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

  • RateLimitingException: If you have sent too many requests within a given period of time.
  • BadRequestException: If the supplied parameters are invalid.
  • AuthenticationException: If your API secret key cannot be authenticated with Magic API server.
  • ForbiddenException: If your API secret key is not authorized to access the resources.
  • ApiException: For any other API error.
  • ApiConnectionException: 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.

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16    $pub_address = $magic->token->get_public_address($did_token);
17    $user_meta = $magic->user->get_metadata_by_public_address($pub_address);
18  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
19    // DIDT is malformed. You can handle this by remapping it to your application
20    // error.
21  } catch (\MagicAdmin\Exception\RequestException $e) {
22    // HTTP error. You can handle this by remapping it to your application error.
23  }

#get_metadata_by_token

Retrieves information about the user by the supplied DID Token.

PHP
01user.get_metadata_by_token(did_token)

#Arguments

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

#Raises

  • RateLimitingException: If you have sent too many requests within a given period of time.
  • BadRequestException: If the supplied parameters are invalid.
  • AuthenticationException: If your API secret key cannot be authenticated with Magic API server.
  • ForbiddenException: If your API secret key is not authorized to access the resources.
  • ApiException: For any other API error.
  • ApiConnectionException: 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.

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16    $user_meta = $magic->user->get_metadata_by_token($did_token);
17  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
18    // DIDT is malformed. You can handle this by remapping it to your application
19    // error.
20  } catch (\MagicAdmin\Exception\RequestException $e) {
21    // HTTP error. You can handle this by remapping it to your application error.
22  }

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

PHP
01user.logout_by_issuer(issuer)

#Arguments

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

#Raises

  • RateLimitingException: If you have sent too many requests within a given period of time.
  • BadRequestException: If the supplied parameters are invalid.
  • AuthenticationException: If your API secret key cannot be authenticated with Magic API server.
  • ForbiddenException: If your API secret key is not authorized to access the resources.
  • ApiException: For any other API error.
  • ApiConnectionException: 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

PHP
01require_once('vendor/autoload.php');
02

03  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
04

05  // Load the user by the `email` which is supplied by the original HTTP request.
06  $user_info = $logic->user->load_by($email)
07

08  try {
09    $magic->user->logout_by_issuer($user_info->issuer);
10  } catch (\MagicAdmin\Exception\RequestException $e) {
11    // HTTP error. You can handle this by remapping it to your application error.
12  }

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

PHP
01user.logout_by_public_address(public_address)

#Arguments

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

#Raises

  • RateLimitingException: If you have sent too many requests within a given period of time.
  • BadRequestException: If the supplied parameters are invalid.
  • AuthenticationException: If your API secret key cannot be authenticated with Magic API server.
  • ForbiddenException: If your API secret key is not authorized to access the resources.
  • ApiException: For any other API error.
  • ApiConnectionException: 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

PHP
01require_once('vendor/autoload.php');
02

03  // Load the user by the `email` which is supplied by the original HTTP request.
04  $user_info = $logic->user->load_by($email)
05

06  try {
07    $magic->user->logout_by_public_address($user_info->pub_address);
08  } catch (\MagicAdmin\Exception\RequestException $e) {
09    // HTTP error. You can handle this by remapping it to your application error.
10  }

#logout_by_token

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

PHP
01user.logout_by_token(did_token)

#Arguments

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

#Raises

  • RateLimitingException: If you have sent too many requests within a given period of time.
  • BadRequestException: If the supplied parameters are invalid.
  • AuthenticationException: If your API secret key cannot be authenticated with Magic API server.
  • ForbiddenException: If your API secret key is not authorized to access the resources.
  • ApiException: For any other API error.
  • ApiConnectionException: 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.

PHP
01require_once('vendor/autoload.php');
02

03  $did_token = \MagicAdmin\Util\Http::parse_authorization_header_value(
04    getallheaders()['authorization']
05  );
06

07  if ($did_token == null) {
08    // DIDT is missing from the original HTTP request header. You can handle this by
09    // remapping it to your application error.
10  }
11

12  $magic = new \MagicAdmin\Magic('<YOUR_API_SECRET_KEY>');
13

14  try {
15    $magic->token->validate($did_token);
16  } catch (\MagicAdmin\Exception\DIDTokenException $e) {
17    // DIDT is malformed. You can handle this by remapping it to your application
18    // error.
19  }
20

21  try {
22    $magic->user->logout_by_token($did_token);
23  } catch (\MagicAdmin\Exception\RequestException $e) {
24    // HTTP error. You can handle this by remapping it to your application error.
25  }

#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 (Array): Raw content returned by the API response.
  • status_code (num): HTTP status code for the given request.
  • data (Array): Parsed content.
PHP
01MagicResponse->content
02MagicResponse->status_code
03MagicResponse->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.

01MagicException
02    |
03    |------- DIDTokenException
04    |
05    |------- RequestException
06                  |
07                  | ------- RateLimitingException
08                  | ------- BadRequestException
09                  | ------- AuthenticationException
10                  | ------- ForbiddenException
11                  | ------- ApiException
12                  | ------- ApiConnectionException

#MagicException

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

PHP
01MagicException(message=null)

#DIDTokenException

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

#RequestException

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

PHP
01RequestException(
02    $message=null,
03    $http_status=null,
04    $http_code=null,
05    $http_resp_data=null,
06    $http_message=null,
07    $http_error_code=null,
08    $http_request_params=null,
09    $http_request_data=null,
10    $http_method=null
11);
CodeErrorDescription
429RateLimitingExceptionToo many requests are submitted for a given period of time.
400BadRequestExceptionThe API requests might have missing required fields or bad inputs.
401AuthenticationExceptionThis means your API secret key is invalid.
403ForbiddenExceptionThis normally means the given API secret key doesn't have permission to perform the action on the given resources.
–ApiExceptionThis is a generic API error that handlers other status codes that are not explicitly handled. Ex: 500 , 404 , etc.
–ApiConnectionExceptionNetwork 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.

PHP
01try{
02    // Make requests to Magic server.
03}
04catch (\MagicAdmin\Exception\DIDTokenException $e) {
05    // throw the exception
06}
07catch (\MagicAdmin\Exception\RateLimitingException $e) {
08    // throw the exception
09}
10catch (\MagicAdmin\Exception\BadRequestException $e) {
11    // throw the exception
12}
13catch (\MagicAdmin\Exception\AuthenticationException $e) {
14    // throw the exception
15}
16catch (\MagicAdmin\Exception\ForbiddenException $e) {
17    // throw the exception
18}
19catch (\MagicAdmin\Exception\ApiException $e) {
20    // throw the exception
21}
22catch (\MagicAdmin\Exception\ApiConnectionException $e) {
23    // throw the exception
24}

Did you find what you were looking for?

PHP API Reference
ConstructorMagicToken Resourceget_issuerget_public_addressdecodevalidateUser Resourceget_metadata_by_issuerget_metadata_by_public_addressget_metadata_by_tokenlogout_by_issuerlogout_by_public_addresslogout_by_tokenResponse and Error HandlingResponseErrors

Did you find what you were looking for?

Product

Magic Connect
Magic Auth
Magic Wallet Services
Pricing

Developers

Documentation
Guides
Help Center
GitHub

Resources

Blog
Status Page
Brand Assets
Whitepaper
Legal
Compliance
Security
Privacy Policy
Trust Center
Whistleblower Hotline

Company

Careers
Contact us

Social

Newsletter
Discord
Twitter
Instagram
Linkedin
YouTube

© 2023 Magic Labs, Inc.

Made with 💜 by Magic Labs

548 Market St., PMB 31387
San Francisco, California 94104-5401

Magic - Use the slickest magic link login in your app | Product Hunt Embed

Product

Magic Connect
Magic Auth
Magic Wallet Services
Pricing

Developers

Documentation
Guides
Help Center
GitHub

Resources

Blog
Status Page
Brand Assets
Whitepaper
Legal
Compliance
Security
Privacy Policy
Trust Center
Whistleblower Hotline

Company

Careers
Contact us

Social

Newsletter
Discord
Twitter
Instagram
Linkedin
YouTube

© 2023 Magic Labs, Inc.

Made with 💜 by Magic Labs

548 Market St., PMB 31387
San Francisco, California 94104-5401

Magic - Use the slickest magic link login in your app | Product Hunt Embed

© 2023 Magic Labs, Inc.

Made with 💜 by Magic Labs

548 Market St., PMB 31387
San Francisco, California 94104-5401

Magic - Use the slickest magic link login in your app | Product Hunt Embed

Product

Magic Connect
Magic Auth
Magic Wallet Services
Pricing

Developers

Documentation
Guides
Help Center
GitHub

Resources

Blog
Status Page
Brand Assets
Whitepaper
Legal
Compliance
Security
Privacy Policy
Trust Center
Whistleblower Hotline

Company

Careers
Contact us

Social

Newsletter
Discord
Twitter
Instagram
Linkedin
YouTube