Clerk Go SDK

Go client library for accessing the Clerk Backend API.

Clerk is Hiring!

Would you like to work on Open Source software and help maintain this repository? Apply today!

Usage

First, add the Clerk SDK as a dependency to your project.

$ go get github.com/clerkinc/clerk-sdk-go

Add the following import to your Go files.

import "github.com/clerkinc/clerk-sdk-go/clerk"

Now, you can create a Clerk client by calling the clerk.NewClient function. This function requires your Clerk API key. You can get this from the dashboard of your Clerk application.

Once you have a client, you can use the various services to access different parts of the API.

apiKey := os.Getenv("CLERK_API_KEY")

client, err := clerk.NewClient(apiKey)
if err != nil {
    // handle error
}

// List all users for current application
users, err := client.Users().ListAll(clerk.ListAllUsersParams{})

The services exposed in the clerk.Client divide the API into logical chunks and follow the same structure that can be found in the Backend API documentation.

For more examples on how to use the client, refer to the examples

Options

The SDK Client constructor can also accept additional options defined here.

A common use case is injecting your own http.Client object for testing or automatically retrying requests. An example using go-retryablehttp is shown below:

retryClient := retryablehttp.NewClient()
retryClient.RetryMax = 5
standardClient := retryClient.StandardClient() // *http.Client

clerkSDKClient := clerk.NewClient(token, clerk.WithHTTPClient(standardClient))

Middleware

The SDK provides the WithSessionV2 middleware that injects the active session into the request's context.

The active session's claims can then be accessed using SessionFromContext.

mux := http.NewServeMux()
injectActiveSession := clerk.WithSessionV2(client)
mux.Handle("/your-endpoint", injectActiveSession(yourEndpointHandler))

Additionally, there's RequireSessionV2 that will halt the request and respond with 403 if the user is not authenticated. This can be used to restrict access to certain routes unless the user is authenticated.

For more info on how to use the middleware, refer to the example.

Additional options

The middleware supports the following options:

clerk.WithAuthorizedParty() to set the authorized parties to check against the azp claim of the token
clerk.WithLeeway() to set a custom leeway that gives some extra time to the token to accommodate for clock skew
clerk.WithJWTVerificationKey() to set the JWK to use for verifying tokens without the need to fetch or cache any JWKs at runtime
clerk.WithCustomClaims() to pass a type (e.g. struct), which will be populated with the token claims based on json tags.
clerk.WithSatelliteDomain() to skip the JWT token's "iss" claim verification.
clerk.WithProxyURL() to verify the JWT token's "iss" claim against the proxy url.

For example

customClaims := myCustomClaimsStruct{}

clerk.WithSessionV2(
	clerkClient,
	clerk.WithAuthorizedParty("my-authorized-party"),
	clerk.WithLeeway(5 * time.Second),
	clerk.WithCustomClaims(&customClaims),
	clerk.WithSatelliteDomain(true),
	clerk.WithProxyURL("https://example.com/__clerk"),
	)

License