Go API Reference

Go API Reference

#Overview

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

Bash
01go get github.com/magiclabs/magic-admin-go
02go get github.com/magiclabs/magic-admin-go/client

#Constructor

#Magic

Parameter

Type

Definition

api_secret_key

String

Your secret API Key retrieved from the Magic Dashboard.

retries

Integer

Total number of retries to allow.

retryWait

time.Duration

A period of time to apply between retry attempts.

timeout

time.Duration

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

#Initialization

Go
01package main
02
03import (
04    "log"
05    "fmt"
06    "time"
07
08    "github.com/magiclabs/magic-admin-go"
09    "github.com/magiclabs/magic-admin-go/client"
10)
11
12func main() {
13    cl := magic.NewClientWithRetry(5, time.Second, 10 * time.Second)
14    m, err := client.New("<SECRET_API_KEY>", cl)
15}

#Token Resource

The Token resource provides methods to interact with DID Token.

note

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

Go
01tk, err := token.NewToken("<DID_TOKEN>")
02if err != nil {
03    log.Fatalf("Malformed DID token error: %s", err.Error())
04}
05
06tk.GetIssuer()
07tk.GetPublicAddress()
08tk.Validate()

#GetIssuer

Extracts the iss from the DID Token.

Go
01tk, err := token.NewToken("<DID_TOKEN>")
02if err != nil {
03    log.Fatalf(err.Error())
04}
05tk.GetIssuer()

#Arguments

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

#Raises

  • token.DIDTokenError: 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.

Go
01tk, err := token.NewToken("<DID_TOKEN>")
02if err != nil {
03    log.Fatalf(err.Error())
04}
05tk.GetPublicAddress()

#Arguments

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

#Raises

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

#Validate

Validates a DID token.

Go
01tk, err := token.NewToken("<DID_TOKEN>")
02if err != nil {
03    log.Fatalf(err.Error())
04}
05err = tk.Validate()

#Arguments

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

#Raises

  • token.DIDTokenError: If the given DID Token is malformed

#Returns

  • boolean value indicating the validity of the token

#User Resource

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

Go
01m, err := client.New("<SECRET_API_KEY>", magic.NewDefaultClient())
02
03m.User
04m.User.GetMetadataByIssuer
05m.User.GetMetadataByPublicAddress
06m.User.GetMetadataByToken
07m.User.LogoutByIssuer
08m.User.LogoutByPublicAddress
09m.User.LogoutByToken

#GetMetadataByIssuer

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.

Go
01userInfo, err := m.User.GetMetadataByIssuer(issuer)

#Arguments

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

#Raises

  • magic.Error: If an error response is received from the Magic API, it will contain information about the error
  • magic.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

#GetMetadataByPublicAddress

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

Go
01userInfo, err := User.GetMetadataByPublicAddress(publicAddress)

#Arguments

#Raises

  • magic.Error: If an error response is received from the Magic API, it will contain information about the error
  • magic.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

#GetMetadataByToken

Retrieves information about the user by the supplied DID Token.

Go
01userInfo, err := User.GetMetadataByToken(didToken)

#Arguments

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

#Raises

  • magic.Error: If an error response is received from the Magic API, it will contain information about the error
  • magic.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

#LogoutByIssuer

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.

Go
01err := User.LogoutByIssuer(issuer)

#Arguments

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

#Raises

  • magic.Error: If an error response is received from the Magic API, it will contain information about the error
  • magic.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

#LogoutByPublicAddress

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

Go
01err := User.LogoutByPublicAddress(publicAddress)

#Arguments

  • publicAddress (string): The user's Ethereum public address

#Raises

  • magic.Error: If an error response is received from the Magic API, it will contain information about the error
  • magic.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

#LogoutByToken

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

Go
01err := User.LogoutByToken(didToken)

#Arguments

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

#Raises

  • magic.Error: If an error response is received from the Magic API, it will contain information about the error
  • magic.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

#Response and Error Handling

It is recommended to implement error handling for API responses.

#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

#Magic Error

magic.Error is the base struct of all the API errors. You can check the error type to determine the API error accordingly.

Go
01_, err := // library call
02
03if err != nil {
04  // Matching error by error type for a failed HTTP request.
05  switch err.(type) {
06    case (*magic.ForbiddenError):
07        // Handle forbidden error.
08    case (*magic.BadRequestError):
09        // Handle bad request error.
10    case (*magic.RateLimitingError):
11        // Handle rate limiting error.
12    case (*magic.AuthenticationError):
13        // Handle authentication error.
14    case (*magic.APIConnectionError):
15        // Handle authentication error.
16    default:
17      fmt.Printf("Other HTTP request error: %v\n", err.Error())
18  }
19}
Http Status CodeError TypeDescription
429magic.RateLimitingErrorToo many requests are submitted for a given period of time.
400magic.BadRequestErrorThe API requests might have missing required fields or bad inputs.
401magic.AuthenticationErrorThis means your API secret key is invalid.
403magic.ForbiddenErrorThis normally means the given API secret key doesn't have permission to perform the action on the given resources.
magic.APIErrorThis is a generic API error that handles other status codes that are not explicitly handled. Ex: 500 , 404 , etc.
magic.APIConnectionErrorNetwork connection error. This normally means the connection between your application and Magic API server cannot be established.

#DIDTokenError

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

#Resources

#Versions

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