Clerk Go SDK

If your application needs to manage multiple Clerk API keys (e.g., in a multi-tenant environment), use the client-based approach. Each resource package exports a NewClient function that returns a client instance configured with a specific key.

To use this pattern:

1. Import the core github.com/clerk/clerk-sdk-go/v2 package and the specific resource package.
2. Create a clerk.ClientConfig and set the Key.
3. Initialize the client using resource.NewClient(config).
4. Call operations directly on the client instance (e.g., client.Get(...)).

import (
    "github.com/clerk/clerk-sdk-go/v2"
    "github.com/clerk/clerk-sdk-go/v2/organization"
)

ctx := context.Background()
config := &clerk.ClientConfig{}
config.Key = clerk.String("sk_live_XXX")
client := organization.NewClient(config)

// Create
org, err := client.Create(ctx, &organization.CreateParams{Name: clerk.String("Clerk Inc")})

Depending on whether you use the global API or the client-based API, there are different ways to mock requests in your tests.

If using the Global API (without client)

1. Custom Transport: Use clerk.SetBackend with a clerk.NewBackend containing a custom http.Client.Transport (implementing http.RoundTripper).
2. httptest Server: Use clerk.SetBackend with a clerk.NewBackend configured with the URL and Client from an httptest.Server.
3. Custom Backend: Implement the clerk.Backend interface and set it via clerk.SetBackend(&myCustomBackend{}).

If using the Client-based API

1. Custom Transport: Pass a clerk.ClientConfig with a custom HTTPClient (containing a mock Transport) to resource.NewClient(config).
2. httptest Server: Pass a clerk.ClientConfig with the HTTPClient and URL from an httptest.Server to resource.NewClient(config).
3. Custom Backend: Assign a custom implementation of the clerk.Backend interface directly to the client instance: client.Backend = &myCustomBackend{}.

// Example: Mocking with a custom transport in a client-based approach
func TestWithCustomTransport(t *testing.T) {
    config := &clerk.ClientConfig{}
    config.HTTPClient = &http.Client{
        Transport: &mockRoundTripper{},
    }
    client := user.NewClient(config)
    client.Get(context.Background(), "user_id")
}

type mockRoundTripper struct {}
func (m *mockRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) {
    return &http.Response{}, nil
}

The v2 library provides middleware in the github.com/clerk/clerk-sdk-go/v2/http package. Note that these only support bearer tokens in the Authorization header; cookie-based authentication is not supported.

Basic Usage

Use clerkhttp.RequireHeaderAuthorization() to protect routes. Access session information in your handlers using clerk.SessionClaimsFromContext(r.Context()).

Using a JWKS Client

If managing multiple API keys, you can pass a jwks.Client to the middleware:

import (
    "net/http"
    "github.com/clerk/clerk-sdk-go/v2"
    clerkhttp "github.com/clerk/clerk-sdk-go/v2/http"
    "github.com/clerk/clerk-sdk-go/v2/jwks"
)

func main() {
    config := &clerk.ClientConfig{}
    config.Key = "sk_live_XXX"
    client := jwks.NewClient(config)
    
    mux := http.NewServeMux()
    withAuth := clerkhttp.RequireHeaderAuthorization(
        clerkhttp.JWKSClient(client),
    )
    mux.Handle("/session", withAuth(http.HandlerFunc(handleSession)))
    http.ListenAndServe(":3000", mux)
}

The SDK provides middleware to handle bearer token authentication in Go HTTP servers. The middleware parses the token, verifies it, and extracts SessionClaims, which are then injected into the http.Request.Context().

Available Middleware

• WithHeaderAuthorization(): Extracts claims and makes them available in the context. If authentication fails, it does not block the request (it's up to your handler to check).
• RequireHeaderAuthorization(): Similar to WithHeaderAuthorization, but automatically responds with HTTP 403 Forbidden if valid session claims are not detected.

Accessing Claims

Use clerk.SessionClaimsFromContext(r.Context()) to retrieve the claims within your handler.

import (
	"fmt"
	"net/http"

	"github.com/clerk/clerk-sdk-go/v2"
	clerkhttp "github.com/clerk/clerk-sdk-go/v2/http"
)

func main() {
	clerk.SetKey("sk_live_XXX")
	mux := http.NewServeMux()
	mux.HandleFunc("/", publicRoute)
	
	// Protect this route
	protectedHandler := http.HandlerFunc(protectedRoute)
	mux.Handle("/protected", clerkhttp.WithHeaderAuthorization()(protectedHandler))

	http.ListenAndServe(":3000", mux)
}

func protectedRoute(w http.ResponseWriter, r *http.Request) {
	claims, ok := clerk.SessionClaimsFromContext(r.Context())
	if !ok {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
	fmt.Fprintf(w, "{\"user_id\": \"%s\"}", claims.Subject)
}