Go SDK

Installation

Current published release: v0.1.10 (verified July 12, 2026).

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

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`

Known v0.1.10 limitations

Registration returns agentId, while Agent.ID expects id; derive the ID from the returned DID.
Registration sends optional zero values; updates cannot set status or send an explicit empty scopes array. Provide registration fields explicitly and use REST for those updates.
The typed audit payload omits required fields; use the REST or CLI audit-write workaround.
AuditEntry omits DeveloperID, and the SDK advertises Since, Until, Page, and PageSize audit filters that the API ignores.
Agent and audit list structs expose Total, Page, and PageSize, but the API returns only agents or entries; use the slice length for this release.
List helpers do not URL-encode reserved characters in filter values; avoid them or issue a REST request with a net/url-encoded query.

Repository source on main corrects all documented v0.1.10 Agent/Audit contract gaps, removes unsupported audit filters, and URL-encodes query values, with API-shaped regression coverage. No corrected module tag has been published. The pinned v0.1.10 install and workarounds remain the supported public-release guidance.

Quick Start

In v0.1.10, the API’s agentId response does not populate Agent.ID because that SDK field expects id. This example derives the ID from the returned did:grantex:<agentId> value. Remove the workaround only after upgrading to a release that corrects the response mapping.

package main

import (
    "context"
    "fmt"
    "log"
    "strings"

    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)
    }
    const didPrefix = "did:grantex:"
    if !strings.HasPrefix(agent.DID, didPrefix) {
        log.Fatal("unexpected agent DID")
    }
    agentID := strings.TrimPrefix(agent.DID, didPrefix)
    fmt.Printf("Agent registered: %s (DID: %s)\n", agentID, agent.DID)

    // 2. Create authorization request
    authReq, err := client.Authorize(ctx, grantex.AuthorizeParams{
        AgentID:     agentID,
        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: agentID,
    })
    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

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)
    }
}

Overview

Authorization

Resources

Reference

Installation

Requirements

Configuration

Known v0.1.10 limitations

Quick Start

Available Resources

Standalone Functions

Error Handling

​Installation

​Requirements

​Configuration

​Known v0.1.10 limitations

​Quick Start

​Available Resources

​Standalone Functions

​Error Handling

Installation

Requirements

Configuration

Known v0.1.10 limitations

Quick Start

Available Resources

Standalone Functions

Error Handling