Skip to main content

​
Authentication Methods

The Garnet API Go SDK supports three distinct authentication methods, each designed for specific use cases:

User Tokens

OAuth 2.0 JWT tokens for user authentication via Auth0

Agent Tokens

API key tokens for agent-specific operations

Project Tokens

API tokens for programmatic access with custom permissions

​
Token Type Enum

The SDK defines a TokenType enum to distinguish between authentication methods:
client/client.go
type TokenType int

const (
	// TokenTypeNone indicates no authentication token is set.
	TokenTypeNone TokenType = iota

	// TokenTypeUser indicates a user authentication token.
	TokenTypeUser

	// TokenTypeAgent indicates an agent authentication token.
	TokenTypeAgent

	// TokenTypeProject indicates a project authentication token.
	TokenTypeProject
)

​
How Authentication Works

When you create a client or configure authentication, the SDK automatically sets the appropriate HTTP headers based on the token type:
Token TypeHTTP HeaderFormat
User TokenAuthorizationBearer <token>
Agent TokenX-Agent-Token<token>
Project TokenX-Project-Token<token>
The SDK automatically handles header formatting. User tokens are prefixed with “Bearer ” if not already present.

​
Client Initialization

The basic client initialization assumes a user token: 
import "github.com/garnet-org/api/client"

// Create client with user token (default)
client := client.New("https://api.garnet.ai", "your-jwt-token")
Never hardcode tokens in your source code. Use environment variables or secure configuration management.

​
Switching Token Types

You can reconfigure an existing client to use different token types: 
// Start with a user token
client := client.New("https://api.garnet.ai", "user-token")

// Switch to agent token
agentClient := client.WithAgentToken("agent-token")

// Switch to project token
projectClient := client.WithProjectToken("project-token")
The With* methods return a cloned client, leaving the original unchanged.

​
Manual Token Configuration

For advanced use cases, you can set both token and type manually:
client/client.go
// SetAuth is a generic method to set both the token and type at once.
func (c *Client) SetAuth(token string, tokenType TokenType) {
	c.AuthToken = token
	c.TokenType = tokenType
}

client.SetAuth("your-token", client.TokenTypeProject)

​
Security Best Practices

1

Use Environment Variables

Store tokens in environment variables, not in source code:
token := os.Getenv("GARNET_API_TOKEN")
client := client.New("https://api.garnet.ai", token)
2

Use Appropriate Token Types

  • User tokens for interactive applications
  • Agent tokens for agent operations only
  • Project tokens for automated workflows and CI/CD
3

Implement Token Rotation

Regularly rotate project and agent tokens to minimize security risks.
4

Apply Least Privilege

Grant project tokens only the permissions they need.

​
Error Handling

Authentication failures return 401 Unauthorized errors: 
err := client.Do(ctx, &result, "GET", "/api/v1/agents", nil)
if err != nil {
    if strings.Contains(err.Error(), "401") {
        // Handle authentication error
        log.Fatal("Authentication failed: invalid or expired token")
    }
}

​
Next Steps

User Tokens

Learn about OAuth 2.0 user authentication

Agent Tokens

Configure agent authentication

Project Tokens

Set up programmatic access

Build docs developers (and LLMs) love

Get started for freeTalk to us