Skip to Content
SDKsGo SDK (auris-go)

Go SDK (auris-go)

github.com/altovar-systems/auris-go is the official Go client library for Auris IAM. It provides idiomatic Go bindings for authentication, user management, and fine-grained authorization using context-aware, error-returning functions.

Go version: 1.21+
Dependencies: net/http (standard library only)


Installation

go get github.com/altovar-systems/auris-go

AurisClient

AurisClient is the main entry point for end-user authentication flows.

Create a client

import auris "github.com/altovar-systems/auris-go" client := auris.NewClient("https://auth.yourdomain.com", "your-client-id")

Quick Start

package main import ( "context" "fmt" "log" auris "github.com/altovar-systems/auris-go" ) func main() { client := auris.NewClient("https://auth.yourdomain.com", "your-client-id") result, err := client.Login(context.Background(), "[email protected]", "password") if err != nil { log.Fatal(err) } fmt.Printf("Logged in as %s\n", result.User.Email) fmt.Printf("Access token: %s\n", result.AccessToken) }

Login

result, err := client.Login(ctx, "[email protected]", "password") // result.AccessToken string // result.RefreshToken string // result.User auris.UserInfo

GetUser

Returns the currently authenticated user from the stored token. Returns nil if not authenticated.

user, err := client.GetUser(ctx) if err != nil { log.Fatal(err) } fmt.Println(user.ID, user.Email, user.Roles)

GetAccessToken

token, err := client.GetAccessToken(ctx) // Use in Authorization: Bearer <token> headers

RefreshToken

result, err := client.RefreshToken(ctx, refreshToken)

GetM2MToken

Obtains a machine-to-machine access token via the OAuth2 client_credentials grant. Never call from browser code.

token, err := client.GetM2MToken(ctx, "client-secret", []string{"read:users", "manage:roles"}) // token.AccessToken string // token.ExpiresIn int
// Send magic link email err := client.LoginWithMagicLink(ctx, "[email protected]") // Verify the token from the link URL result, err := client.VerifyMagicLink(ctx, "token-from-url")

Logout

err := client.Logout(ctx)

ManagementClient

ManagementClient is for server-side tenant management using M2M credentials.

Only use ManagementClient in server-side code. The client secret must never be exposed to browsers or end users.

mgmt, err := auris.NewManagementClient( ctx, "https://auth.yourdomain.com", "your-client-id", "your-client-secret", ) if err != nil { log.Fatal(err) }

Users

// List users users, err := mgmt.ListUsers(ctx) // Get a single user user, err := mgmt.GetUser(ctx, "user-id") // Create a user user, err := mgmt.CreateUser(ctx, map[string]interface{}{ "email": "[email protected]", "name": "New User", }) // Delete a user err = mgmt.DeleteUser(ctx, "user-id") // Assign roles err = mgmt.AssignRoles(ctx, "user-id", []string{"role-id-1", "role-id-2"}) // Remove roles err = mgmt.RemoveRoles(ctx, "user-id", []string{"role-id-1"})

Organizations

// List organizations orgs, err := mgmt.ListOrganizations(ctx) // Get an organization org, err := mgmt.GetOrganization(ctx, "org-id") // Create an organization org, err := mgmt.CreateOrganization(ctx, map[string]interface{}{ "name": "Acme Corp", }) // Delete an organization err = mgmt.DeleteOrganization(ctx, "org-id") // List members members, err := mgmt.ListMembers(ctx, "org-id") // Add a member err = mgmt.AddMember(ctx, "org-id", "user-id", "member") // Remove a member err = mgmt.RemoveMember(ctx, "org-id", "user-id")

Roles

roles, err := mgmt.ListRoles(ctx)

FgaClient

FgaClient implements Zanzibar-style fine-grained authorization. Requires the FGA feature to be enabled on your tenant.

fga, err := auris.NewFgaClient( ctx, "https://auth.yourdomain.com", "your-client-id", "your-client-secret", ) if err != nil { log.Fatal(err) }

CheckPermission

allowed, err := fga.CheckPermission(ctx, "user:alice", "read", "document:budget") if err != nil { log.Fatal(err) } fmt.Println("Allowed:", allowed)

CheckPermissions

checks := []auris.PermissionCheck{ {User: "user:alice", Relation: "read", Object: "document:budget"}, {User: "user:alice", Relation: "write", Object: "document:budget"}, } results, err := fga.CheckPermissions(ctx, checks)

TupleWrite

err = fga.TupleWrite(ctx, []auris.PermissionCheck{ {User: "user:bob", Relation: "viewer", Object: "document:report"}, })

Webhook Verification

import ( "io" "net/http" auris "github.com/altovar-systems/auris-go" ) func webhookHandler(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "Bad request", http.StatusBadRequest) return } signature := r.Header.Get("X-Auris-Signature") if !auris.VerifyWebhookSignature(body, signature, "your-webhook-secret") { http.Error(w, "Invalid signature", http.StatusUnauthorized) return } // Process webhook event... w.WriteHeader(http.StatusOK) }

Error Handling

All methods return a Go error. For Auris-specific errors, use errors.As to unwrap the AurisError type and inspect the HTTP status code and message.

import ( "errors" "fmt" auris "github.com/altovar-systems/auris-go" ) result, err := client.Login(ctx, email, password) if err != nil { var aurisErr *auris.AurisError if errors.As(err, &aurisErr) { fmt.Printf("HTTP %d: %s\n", aurisErr.StatusCode, aurisErr.Message) } else { fmt.Println("Network error:", err) } }

Common error codes:

CodeStatusDescription
invalid_credentials401Wrong email or password
invalid_token401Token is expired or malformed
permission_denied403User lacks the required permission
not_found404Resource does not exist
rate_limited429Too many requests