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-goAurisClient
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.UserInfoGetUser
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> headersRefreshToken
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 intLoginWithMagicLink / VerifyMagicLink
// 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:
| Code | Status | Description |
|---|---|---|
invalid_credentials | 401 | Wrong email or password |
invalid_token | 401 | Token is expired or malformed |
permission_denied | 403 | User lacks the required permission |
not_found | 404 | Resource does not exist |
rate_limited | 429 | Too many requests |
Related Pages
- JavaScript SDK — Browser, Node.js, and edge runtimes
- Python SDK — Python 3.8+ with httpx
- Rust SDK — Async/await with tokio
- Fine-Grained Authorization — FGA model and tuple management
- Webhooks — Webhook delivery and HMAC verification