# Clerk Go SDK

**Before you start**

- [Set up a Clerk application](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md?sdk=go)

The [Clerk Go SDK](https://clerk.com/docs/go/reference/go/overview.md) is built on top of the [Clerk Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}.

## Installation

If you're using Go Modules and have a `go.mod` file in your project's root, you can import `clerk-sdk-go` directly in your `.go` files:

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

Alternatively, you can `go get` the package explicitly and it will add the necessary dependencies to your `go.mod` file:

filename: terminal
```sh
go get -u github.com/clerk/clerk-sdk-go/v2
```

## Usage

For details on how to use this module, see the [Go Documentation](https://pkg.go.dev/github.com/clerk/clerk-sdk-go/v2).

The Clerk Go SDK is organized using a resource-based structure similar to the [Clerk Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. Each API supports specific operations, like `Create` or `List`. For example, the [`actortoken`](https://github.com/clerk/clerk-sdk-go/blob/v2/actortoken/api.go) resource supports the `Create`, `Revoke`, and `GetClient` operations. For the list of supported resources, see [`https://github.com/clerk/clerk-sdk-go/tree/v2`](https://github.com/clerk/clerk-sdk-go/tree/v2) where almost each directory represents a resource.

To execute API operations, you must configure Clerk Go with your Clerk Secret Key.

Depending on your use case, there are two ways to use the Clerk Go SDK:

- [Without a client](https://clerk.com/docs/go/getting-started/quickstart.md#usage-without-a-client): The best option if you're using one API key.
- [With a client](https://clerk.com/docs/go/getting-started/quickstart.md#usage-with-a-client): The best option if you're using more than one API key.

For most use cases, the API **without** a client is a better choice as it requires a minimal setup and provides a more concise API for invoking operations. However, if you need to operate on multiple Clerk instances from one application, or need more flexibility for tests and mocking, you can instantiate multiple API clients with different API keys.

The following examples demonstrate both approaches.

### Usage without a client

If you only use one API key, you can import the packages required for the APIs you need. Then you can execute your desired request methods as functions, such as `$resource$.Get()` or `$resource$.Delete()`, where `$resource$` is the resource you want to interact with, such as [`user`](https://github.com/clerk/clerk-sdk-go/blob/v2/user/api.go).

filename: main.go
```go
package main

import (
  "context"

  "github.com/clerk/clerk-sdk-go/v2"
  "github.com/clerk/clerk-sdk-go/v2/user"
)

func main() {
    // Each operation requires a context.Context as the first argument
    ctx := context.Background()

    // Set the API key with your Clerk Secret Key
    clerk.SetKey("{{secret}}")

    // Create a new user
    newUser, err := user.Create(ctx, &user.CreateParams{})
    if err != nil {
        // Handle error
    }

    // Get user details
    userDetails, err := user.Get(ctx, "user_id")
    if err != nil {
        // Handle error
    }

    // List users
    userList, err := user.List(ctx, &user.ListParams{})
    if err != nil {
        // Handle error
    }
    for _, u := range userList.Users {
        // Process each user
    }

    // Delete user
    deletedResource, err := user.Delete(ctx, "user_id")
    if err != nil {
        // Handle error
    }
}
```

#### Example

The following example demonstrates how to use the Clerk Go SDK to execute [Clerk Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }} operations.

By executing the code in the snippet below, you will:

- Create an Organization and update its slug.
- Fetch all Organization memberships and loop through them to get the first one.
- Get more details about the Organization's user.

> Your Clerk Secret Key is required. If you're signed into the Clerk Dashboard, your Secret Key should become visible by selecting the eye icon. Otherwise, you can retrieve your Clerk Secret Key on the [**API keys**](https://dashboard.clerk.com/~/api-keys) page in the Clerk Dashboard.

filename: main.go
```go
import (
    "github.com/clerk/clerk-sdk-go/v2"
    "github.com/clerk/clerk-sdk-go/v2/organization"
    "github.com/clerk/clerk-sdk-go/v2/organizationmembership"
    "github.com/clerk/clerk-sdk-go/v2/user"
)

func main() {
  // Each API operation requires a context.Context as the first argument.
  ctx := context.Background()

  // Set the API key
  clerk.SetKey("{{secret}}")

  // Create an organization
  org, err := organization.Create(ctx, &organization.CreateParams{
      Name: clerk.String("Clerk Inc"),
  })
  if err != nil {
    // You can get additional information on the error, if it can
    // be type-cast to clerk.APIErrorResponse.
    if apiErr, ok := err.(*clerk.APIErrorResponse); ok {
      apiErr.TraceID
      apiErr.Error()
      apiErr.Response.RawJSON
    }
    // handle the error
    panic(err)
  }

  // Update the organization
  org, err = organization.Update(ctx, org.ID, &organization.UpdateParams{
      Slug: clerk.String("clerk"),
  })
  if err != nil {
    // handle the error
    panic(err)
  }

  // List organization memberships
  listParams := organizationmembership.ListParams{}
  listParams.Limit = clerk.Int64(10)
  memberships, err := organizationmembership.List(ctx, params)
  if err != nil {
    // handle the error
    panic(err)
  }
  if memberships.TotalCount < 0 {
      return
  }
  membership := memberships[0]

  // Get a user
  usr, err := user.Get(ctx, membership.UserID)
  if err != nil {
    // handle the error
    panic(err)
  }
}
```

### Usage with a client

If you're working with multiple keys, it's recommended to use Clerk Go with a client. The API packages for each resource export a `Client`, which supports all the API's operations. This way, you can create as many clients as needed, each with their own API key, as shown in the following example:

filename: main.go
```go
package main

import (
  "context"

  "github.com/clerk/clerk-sdk-go/v2"
  "github.com/clerk/clerk-sdk-go/v2/user"
)

func main() {
    // Each operation requires a context.Context as the first argument.
    ctx := context.Background()

    // Initialize a client with an API key
    config := &clerk.ClientConfig{}
    config.Key = "{{secret}}"
    client := user.NewClient(config)

    // Create a new user
    newUser, err := client.Create(ctx, &user.CreateParams{})
    if err != nil {
        // Handle error
    }

    // Get user details
    userDetails, err := client.Get(ctx, "user_id")
    if err != nil {
        // Handle error
    }

    // List users
    userList, err := client.List(ctx, &user.ListParams{})
    if err != nil {
        // Handle error
    }
    for _, u := range userList.Users {
        // Process each user
    }

    // Delete user
    deletedResource, err := client.Delete(ctx, "user_id")
    if err != nil {
        // Handle error
    }
}
```

## Next steps

Learn more about the Clerk Go SDK and the underlying Backend API it's built on, using the following guides.

- [Verify a Clerk session in Go](https://clerk.com/docs/guides/sessions/verifying.md?sdk=go): Learn how to verify a Clerk session in your Go application.
- [Backend API reference](https://clerk.com/docs/reference/backend-api): Learn more about the Clerk's Backend API that powers the Clerk Go SDK.
- [Clerk Go SDK reference](https://clerk.com/docs/reference/go/overview.md?sdk=go): Learn about the Clerk Go SDK and how to integrate it into your app.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)