Go SDK

Official Go SDK for the Grantex delegated authorization protocol

Installation

Published release: github.com/mishrasanjeev/grantex-go@v0.3.0. The tag, public Go proxy, clean module install, standard tests, and race tests were verified before this page was updated.

go get github.com/mishrasanjeev/grantex-go@v0.3.0

The unpinned go get github.com/mishrasanjeev/grantex-go command follows Go’s module-version resolution. Keep the exact version above in reproducible builds. See Release Status before upgrading.

Requirements

• Go 1.26.1+, matching this module’s go.mod directive

Configuration

import grantex "github.com/mishrasanjeev/grantex-go"

// Default configuration (reads GRANTEX_API_KEY is not used here — pass key directly)
client := grantex.NewClient("your-api-key")

// With options
client := grantex.NewClient("your-api-key",
    grantex.WithBaseURL("https://your-instance.example.com"),
    grantex.WithTimeout(60 * time.Second),
    grantex.WithHTTPClient(customHTTPClient),
)

Option	Default	Description
WithBaseURL(url)	https://api.grantex.dev	API base URL
WithTimeout(d)	30s	HTTP request timeout
WithHTTPClient(c)	http.DefaultClient	Custom *http.Client

Version v0.3.0 adds typed EVM payment responses and authenticated principal/agent reservation reconciliation for Base USDC custody. It retains bounded refresh lost-response recovery from v0.2.1 and the corrected Agent/Audit contracts and ES256 DPoP wallet clients from v0.2.0. It does not add an automatic x402 HTTP payment-and-retry wrapper; applications must implement their merchant HTTP flow.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    grantex "github.com/mishrasanjeev/grantex-go"
)

func main() {
    ctx := context.Background()
    client := grantex.NewClient("your-api-key")

    // 1. Register an agent
    agent, err := client.Agents.Register(ctx, grantex.RegisterAgentParams{
        Name:        "Email Assistant",
        Description: "Reads and sends emails on behalf of users",
        Scopes:      []string{"read:email", "send:email"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Agent registered: %s (DID: %s)\n", agent.ID, agent.DID)

    // 2. Create authorization request
    authReq, err := client.Authorize(ctx, grantex.AuthorizeParams{
        AgentID:     agent.ID,
        PrincipalID: "user-123",
        Scopes:      []string{"read:email", "send:email"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Consent URL: %s\n", authReq.ConsentURL)

    // 3. Exchange authorization code for token (after user consents)
    tokenResp, err := client.Tokens.Exchange(ctx, grantex.ExchangeTokenParams{
        Code:    "authorization-code-from-callback",
        AgentID: agent.ID,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Grant token: %s\n", tokenResp.GrantToken)

    // 4. Verify the token
    verified, err := client.Tokens.Verify(ctx, tokenResp.GrantToken)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Token valid: %v, scopes: %v\n", verified.Valid, verified.Scopes)
}

Available Resources

Service	Description
client.Agents	Register, list, update, delete agents
client.Tokens	Exchange, refresh, verify, revoke tokens
client.Grants	List, revoke, delegate grants
client.Audit	Log and query audit entries
client.Webhooks	Manage webhook endpoints
client.Billing	Subscription and checkout management
client.Policies	Access policy CRUD
client.Compliance	Compliance reports and evidence packs
client.Anomalies	Anomaly detection and management
client.SCIM	SCIM 2.0 user provisioning
client.SSO	SSO configuration
client.PrincipalSessions	End-user dashboard sessions
client.Passports	Issue, list, get, and revoke MPP agent passports
client.Vault	Store, list, get, delete, and exchange service credentials
client.Budgets	Per-grant spending budgets and transactions
client.Events	SSE event streaming
client.Usage	Usage metering and history
client.Domains	Custom domain verification
client.WebAuthn	FIDO2/WebAuthn passkey management
client.Credentials	Verifiable Credentials and SD-JWT
client.Commerce	Commerce V1/OACP merchant discovery, catalog, checkout, webhooks, and ops
client.DPDP	DPDP Act 2023 compliance — consent, grievances, erasure, exports
client.WalletSpendPolicies	Developer-level layered wallet policy

Use NewPrincipalPrepaidWalletClient for human wallet, assignment, reload, policy, approval, activity, and stop operations. Use NewAgentPrepaidWalletClient with GenerateDPoPKey for assigned-wallet listing, payment authorization, and reload requests. Both constructors reject remote plain-HTTP wallet endpoints; check their returned errors. See Agent Wallet Governance.

Standalone Functions

Function	Description
grantex.VerifyGrantToken()	Local JWT verification with a JWKS fetch per standalone call
grantex.GeneratePKCE()	Generate PKCE S256 challenge pair
grantex.VerifyWebhookSignature()	Verify HMAC-SHA256 webhook signatures
grantex.Signup()	Register a new developer (no API key needed)

Error Handling

agent, err := client.Agents.Get(ctx, "agent-id")
if err != nil {
    switch e := err.(type) {
    case *grantex.AuthError:
        fmt.Printf("Authentication failed: %d\n", e.StatusCode)
    case *grantex.APIError:
        fmt.Printf("API error %d: %s (code: %s)\n", e.StatusCode, e.Message, e.Code)
    case *grantex.NetworkError:
        fmt.Printf("Network error: %s\n", e.Message)
    default:
        fmt.Printf("Unexpected error: %v\n", err)
    }
}

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].