Go API Reference
Go 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.
Go
01cl := magic.NewClientWithRetry(retries, retryWait, timeout)
02m := client.New("<api_secret_key>", cl)
#Arguments
retries(int): 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.api_secret_key(string): Your API secret Key retrieved from the Magic Dashboard.
#Returns
- A
Clientobject that implements methods to interact with Magic API.
#Examples
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 := client.New("<api_secret_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.
#Error
token.DIDTokenError if the given DID Token is malformed.
#Returns
A Decentralized ID (iss) of the Magic user who generated the DID Token.
#Example
We are using Google AppEngine for an example below.
important
It is important to always validate the DID Token before using.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/token"
12)
13
14const authBearer = "Bearer"
15
16func main() {
17 http.HandleFunc("/v1/user/info", handler)
18 port := os.Getenv("PORT")
19 log.Printf("Listening on port %s", port)
20 if err := http.ListenAndServe(":"+port, nil); err != nil {
21 log.Fatal(err)
22 }
23}
24
25func handler(w http.ResponseWriter, r *http.Request) {
26 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
27 fmt.Fprintf(w, "Bearer token is required")
28 return
29 }
30
31 did := r.Header.Get("Authorization")[len(authBearer)+1:]
32 if did == "" {
33 fmt.Fprintf(w, "DID token is required")
34 return
35 }
36
37 tk, err := token.NewToken(did)
38 if err != nil {
39 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
40 return
41 }
42
43 if err := tk.Validate(); err != nil {
44 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
45 return
46 }
47
48 return tk.GetIssuer())
49
50}
#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.
#Error
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.
#Example
We are using Google AppEngine for an example below.
important
It is important to always validate the DID Token before using.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/token"
12)
13
14const authBearer = "Bearer"
15
16func main() {
17 http.HandleFunc("/v1/user/info", handler)
18 port := os.Getenv("PORT")
19 log.Printf("Listening on port %s", port)
20 if err := http.ListenAndServe(":"+port, nil); err != nil {
21 log.Fatal(err)
22 }
23}
24
25func handler(w http.ResponseWriter, r *http.Request) {
26 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
27 fmt.Fprintf(w, "Bearer token is required")
28 return
29 }
30
31 did := r.Header.Get("Authorization")[len(authBearer)+1:]
32 if did == "" {
33 fmt.Fprintf(w, "DID token is required")
34 return
35 }
36
37 tk, err := token.NewToken(did)
38 if err != nil {
39 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
40 return
41 }
42
43 if err := tk.Validate(); err != nil {
44 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
45 return
46 }
47
48 return tk.GetPublicAddress())
49}
#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.
#Error
token.DIDTokenErrorif the given DID Token is malformed.
#Example
We are using Google AppEngine for an example below.
important
It is important to always validate the DID Token before using.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/token"
12)
13
14const authBearer = "Bearer"
15
16func main() {
17 http.HandleFunc("/v1/user/info", handler)
18 port := os.Getenv("PORT")
19 log.Printf("Listening on port %s", port)
20 if err := http.ListenAndServe(":"+port, nil); err != nil {
21 log.Fatal(err)
22 }
23}
24
25func handler(w http.ResponseWriter, r *http.Request) {
26 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
27 fmt.Fprintf(w, "Bearer token is required")
28 return
29 }
30
31 did := r.Header.Get("Authorization")[len(authBearer)+1:]
32 if did == "" {
33 fmt.Fprintf(w, "DID token is required")
34 return
35 }
36
37 tk, err := token.NewToken(did)
38 if err != nil {
39 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
40 return
41 }
42
43 if err := tk.Validate(); err != nil {
44 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
45 return
46 }
47
48 return tk
49}
#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 := client.New("<YOUR_API_SECRET_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
#Error
- A
magic.Error: In case of an error response from the Magic API, it will contain information about the error. - A
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 : Contains all of the user meta information.
Issuer(string): The user's Decentralized ID.Email(string): The user's email address.PublicAddress(string): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
#Example
We are using Google AppEngine for an example below.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/client"
12 "github.com/magiclabs/magic-admin-go/token"
13)
14
15const authBearer = "Bearer"
16
17func main() {
18 http.HandleFunc("/v1/user/update", handler)
19 port := os.Getenv("PORT")
20 log.Printf("Listening on port %s", port)
21 if err := http.ListenAndServe(":"+port, nil); err != nil {
22 log.Fatal(err)
23 }
24}
25
26func handler(w http.ResponseWriter, r *http.Request) {
27 m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
28
29 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
30 fmt.Fprintf(w, "Bearer token is required")
31 return
32 }
33
34 did := r.Header.Get("Authorization")[len(authBearer)+1:]
35 if did == "" {
36 fmt.Fprintf(w, "DID token is required")
37 return
38 }
39
40 tk, err := token.NewToken(did)
41 if err != nil {
42 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
43 return
44 }
45
46 if err := tk.Validate(); err != nil {
47 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
48 return
49 }
50
51 userInfo, err := m.User.GetMetadataByIssuer(tk.GetIssuer())
52 if err != nil {
53 fmt.Fprintf(w, "Error: %s", err.Error())
54 return
55 }
56
57 return userInfo
58}
#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
publicAddress (string): The user's Ethereum public address, which can be parsed using Token.GetPublicAddress.
#Error
- A
magic.Error: In case of an error response from the Magic API, it will contain information about the error. - A
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 : Contains all of the user meta information.
Issuer(string): The user's Decentralized ID.Email(string): The user's email address.PublicAddress(string): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
#Example
We are using Google AppEngine for an example below.
important
It is important to always validate the DID Token before using.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/client"
12 "github.com/magiclabs/magic-admin-go/token"
13)
14
15const authBearer = "Bearer"
16
17func main() {
18 http.HandleFunc("/v1/user/update", handler)
19 port := os.Getenv("PORT")
20 log.Printf("Listening on port %s", port)
21 if err := http.ListenAndServe(":"+port, nil); err != nil {
22 log.Fatal(err)
23 }
24}
25
26func handler(w http.ResponseWriter, r *http.Request) {
27 m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
28
29 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
30 fmt.Fprintf(w, "Bearer token is required")
31 return
32 }
33
34 did := r.Header.Get("Authorization")[len(authBearer)+1:]
35 if did == "" {
36 fmt.Fprintf(w, "DID token is required")
37 return
38 }
39
40 tk, err := token.NewToken(did)
41 if err != nil {
42 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
43 return
44 }
45
46 if err := tk.Validate(); err != nil {
47 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
48 return
49 }
50
51 userInfo, err := m.User.GetMetadataByPublicAddress(tk.GetPublicAddress())
52 if err != nil {
53 fmt.Fprintf(w, "Error: %s", err.Error())
54 return
55 }
56
57 return userInfo
58}
#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.
#Error
- A
magic.Error: In case of an error response from the Magic API, it will contain information about the error. - A
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 : Contains all of the user meta information.
Issuer(string): The user's Decentralized ID.Email(string): The user's email address.PublicAddress(string): The authenticated user's public address (a.k.a.: public key). Currently, this value is associated with the Ethereum blockchain.
#Example
We are using Google AppEngine for an example below.
important
It is important to always validate the DID Token before using.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/client"
12)
13
14const authBearer = "Bearer"
15
16func main() {
17 http.HandleFunc("/v1/user/update", handler)
18 port := os.Getenv("PORT")
19 log.Printf("Listening on port %s", port)
20 if err := http.ListenAndServe(":"+port, nil); err != nil {
21 log.Fatal(err)
22 }
23}
24
25func handler(w http.ResponseWriter, r *http.Request) {
26 m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
27
28 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
29 fmt.Fprintf(w, "Bearer token is required")
30 return
31 }
32
33 did := r.Header.Get("Authorization")[len(authBearer)+1:]
34 if did == "" {
35 fmt.Fprintf(w, "DID token is required")
36 return
37 }
38
39 tk, err := token.NewToken(did)
40 if err != nil {
41 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
42 return
43 }
44
45 if err := tk.Validate(); err != nil {
46 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
47 return
48 }
49
50 userInfo, err := m.User.GetMetadataByToken(did)
51 if err != nil {
52 fmt.Fprintf(w, "Error: %s", err.Error())
53 return
54 }
55
56 return userInfo
57}
#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)
#Error
- A
magic.Error: In case of an error response from the Magic API, it will contain information about the error. - A
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.
#Arguments
issuer (string): The user's Decentralized ID, which can be parsed using Token.GetIssuer
#Example
We are using Google AppEngine for an example below.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08
09 "github.com/magiclabs/magic-admin-go"
10 "github.com/magiclabs/magic-admin-go/client"
11)
12
13func main() {
14 http.HandleFunc("/v1/user/logout", handler)
15 port := os.Getenv("PORT")
16 log.Printf("Listening on port %s", port)
17 if err := http.ListenAndServe(":"+port, nil); err != nil {
18 log.Fatal(err)
19 }
20}
21
22func handler(w http.ResponseWriter, r *http.Request) {
23 m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
24
25 // Use your logic to load user by user_id.
26 userId := r.URL.Query().Get("user_id")
27 user := logic.User.LoadById(userId)
28
29 if tk.GetIssuer() != user.Issuer {
30 fmt.Fprintf(w, "The request is not authorized.")
31 return
32 }
33
34 err := m.User.LogoutByIssuer(user.Issuer)
35 if err != nil {
36 fmt.Fprintf(w, "Error: %s", err.Error())
37 return
38 }
39}
#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.
#Error
- A
magic.Error: In case of an error response from the Magic API, it will contain information about the error. - A
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.
#Example
We are using Google AppEngine for an example below.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08
09 "github.com/magiclabs/magic-admin-go"
10 "github.com/magiclabs/magic-admin-go/client"
11)
12
13func main() {
14 http.HandleFunc("/v1/user/logout", handler)
15 port := os.Getenv("PORT")
16 log.Printf("Listening on port %s", port)
17 if err := http.ListenAndServe(":"+port, nil); err != nil {
18 log.Fatal(err)
19 }
20}
21
22func handler(w http.ResponseWriter, r *http.Request) {
23 m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
24
25 // User your logic to oad user by the user_id.
26 userId := r.URL.Query().Get("user_id")
27 user := logic.User.LoadById(userId)
28
29 if tk.GetPublicAddress() != user.PublicAddress {
30 fmt.Fprintf(w, "Request is not authorized.")
31 return
32 }
33
34 err := m.User.LogoutByPublicAddress(user.PublicAddress)
35 if err != nil {
36 fmt.Fprintf(w, "Error: %s", err.Error())
37 return
38 }
39}
#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.
#Error
- A
magic.Error: In case of an error response from the Magic API, it will contain information about the error. - A
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.
#Example
We are using Google AppEngine for an example below.
important
It is important to always validate the DID Token before using.
Go
01package main
02
03import (
04 "fmt"
05 "log"
06 "net/http"
07 "os"
08 "strings"
09
10 "github.com/magiclabs/magic-admin-go"
11 "github.com/magiclabs/magic-admin-go/client"
12 "github.com/magiclabs/magic-admin-go/token"
13)
14
15const authBearer = "Bearer"
16
17func main() {
18 http.HandleFunc("/v1/user/logout", handler)
19 port := os.Getenv("PORT")
20 log.Printf("Listening on port %s", port)
21 if err := http.ListenAndServe(":"+port, nil); err != nil {
22 log.Fatal(err)
23 }
24}
25
26func handler(w http.ResponseWriter, r *http.Request) {
27 m := client.New("<YOUR_API_SECRET_KEY>", magic.NewDefaultClient())
28
29 if !strings.HasPrefix(r.Header.Get("Authorization"), authBearer) {
30 fmt.Fprintf(w, "Bearer token is required")
31 return
32 }
33
34 did := r.Header.Get("Authorization")[len(authBearer)+1:]
35 if did == "" {
36 fmt.Fprintf(w, "DID token is required")
37 return
38 }
39
40 tk, err := token.NewToken(did)
41 if err != nil {
42 fmt.Fprintf(w, "Malformed DID token error: %s", err.Error())
43 return
44 }
45
46 if err := tk.Validate(); err != nil {
47 fmt.Fprintf(w, "DID token failed validation: %s", err.Error())
48 return
49 }
50
51 // Use your logic to load user by user_id.
52 userId := r.URL.Query().Get("user_id")
53 user := logic.User.LoadById(userId)
54
55 if tk.GetIssuer() != user.Issuer {
56 fmt.Fprintf(w, "Request is not authorized")
57 return
58 }
59
60 err := m.User.LogoutByToken(did)
61 if err != nil {
62 fmt.Fprintf(w, "Error: %s", err.Error())
63 return
64 }
65}
#Error Handling
#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 StatusCode | Error Type | Description |
| 429 | magic.RateLimitingError | Too many requests are submitted for a given period of time. |
| 400 | magic.BadRequestError | The API requests might have missing required fields or bad inputs. |
| 401 | magic.AuthenticationError | This means your API secret key is invalid. |
| 403 | magic.ForbiddenError | This normally means the given API secret key doesn't have permission to perform the action on the given resources. |
| – | magic.APIError | This is a generic API error that handles other status codes that are not explicitly handled. Ex: 500 , 404 , etc. |
| – | magic.APIConnectionError | Network connection error. This normally means the connection between your application and Magic API server cannot be established. |
