github.com/clerkinc/clerk-sdk-go@v1.49.1/README.md (about)

     1  <p align="center">
     2    <a href="https://www.clerk.com/?utm_source=github&utm_medium=starter_repos&utm_campaign=sdk_go" target="_blank" align="center">
     3      <picture>
     4        <source media="(prefers-color-scheme: dark)" srcset="./docs/clerk-logo-dark.png">
     5        <img src="./docs/clerk-logo-light.png" height="64">
     6      </picture>
     7    </a>
     8    <br />
     9  </p>
    10  
    11  # Clerk Go SDK
    12  
    13  Go client library for accessing the [Clerk Backend API](https://clerk.com/docs/reference/backend-api).
    14  
    15  [![GoDoc](https://img.shields.io/static/v1?label=godoc&message=reference&color=blue)](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/clerk)
    16  [![Test Status](https://github.com/clerkinc/clerk-sdk-go/workflows/tests/badge.svg)](https://github.com/clerkinc/clerk-sdk-go/actions?query=workflow%3Atests)
    17  
    18  [![chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://discord.com/invite/b5rXHjAg7A)
    19  [![documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs)
    20  [![twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev)
    21  
    22  ---
    23  
    24  **Clerk is Hiring!**
    25  
    26  Would you like to work on Open Source software and help maintain this repository? [Apply today!](https://jobs.ashbyhq.com/clerk)
    27  
    28  ---
    29  
    30  ## Usage
    31  
    32  First, add the Clerk SDK as a dependency to your project.
    33  
    34  ```
    35  $ go get github.com/clerkinc/clerk-sdk-go
    36  ```
    37  
    38  Add the following import to your Go files.
    39  
    40  ```go
    41  import "github.com/clerkinc/clerk-sdk-go/clerk"
    42  ```
    43  
    44  Now, you can create a Clerk client by calling the `clerk.NewClient` function.
    45  This function requires your Clerk API key.
    46  You can get this from the dashboard of your Clerk application.
    47  
    48  Once you have a client, you can use the various services to access different parts of the API.
    49  
    50  ```go
    51  apiKey := os.Getenv("CLERK_API_KEY")
    52  
    53  client, err := clerk.NewClient(apiKey)
    54  if err != nil {
    55      // handle error
    56  }
    57  
    58  // List all users for current application
    59  users, err := client.Users().ListAll(clerk.ListAllUsersParams{})
    60  ```
    61  
    62  The services exposed in the `clerk.Client` divide the API into logical chunks and
    63  follow the same structure that can be found in the [Backend API documentation](https://clerk.com/docs/reference/backend-api).
    64  
    65  For more examples on how to use the client, refer to the [examples](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/operations)
    66  
    67  ### Options
    68  
    69  The SDK `Client` constructor can also accept additional options defined [here](https://github.com/clerk/clerk-sdk-go/blob/main/clerk/clerk_options.go).
    70  
    71  A common use case is injecting your own [`http.Client` object](https://pkg.go.dev/net/http#Client) for testing or automatically retrying requests.
    72  An example using [go-retryablehttp](https://github.com/hashicorp/go-retryablehttp/#getting-a-stdlib-httpclient-with-retries) is shown below:
    73  
    74  ```go
    75  retryClient := retryablehttp.NewClient()
    76  retryClient.RetryMax = 5
    77  standardClient := retryClient.StandardClient() // *http.Client
    78  
    79  clerkSDKClient := clerk.NewClient(token, clerk.WithHTTPClient(standardClient))
    80  ```
    81  
    82  ## Middleware
    83  
    84  The SDK provides the [`WithSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#WithSessionV2) middleware that injects the active session into the request's context.
    85  
    86  The active session's claims can then be accessed using [`SessionFromContext`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#SessionFromContext).
    87  
    88  ```go
    89  mux := http.NewServeMux()
    90  injectActiveSession := clerk.WithSessionV2(client)
    91  mux.Handle("/your-endpoint", injectActiveSession(yourEndpointHandler))
    92  ```
    93  
    94  Additionally, there's [`RequireSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#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.
    95  
    96  For more info on how to use the middleware, refer to the
    97  [example](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/middleware).
    98  
    99  ### Additional options
   100  
   101  The middleware supports the following options:
   102  
   103  - clerk.WithAuthorizedParty() to set the authorized parties to check against the azp claim of the token
   104  - clerk.WithLeeway() to set a custom leeway that gives some extra time to the token to accommodate for clock skew
   105  - clerk.WithJWTVerificationKey() to set the JWK to use for verifying tokens without the need to fetch or cache any JWKs at runtime
   106  - clerk.WithCustomClaims() to pass a type (e.g. struct), which will be populated with the token claims based on json tags.
   107  - clerk.WithSatelliteDomain() to skip the JWT token's "iss" claim verification.
   108  - clerk.WithProxyURL() to verify the JWT token's "iss" claim against the proxy url.
   109  
   110  For example
   111  
   112  ```golang
   113  customClaims := myCustomClaimsStruct{}
   114  
   115  clerk.WithSessionV2(
   116  	clerkClient,
   117  	clerk.WithAuthorizedParty("my-authorized-party"),
   118  	clerk.WithLeeway(5 * time.Second),
   119  	clerk.WithCustomClaims(&customClaims),
   120  	clerk.WithSatelliteDomain(true),
   121  	clerk.WithProxyURL("https://example.com/__clerk"),
   122  	)
   123  ```
   124  
   125  ## License
   126  
   127  This SDK is licensed under the MIT license found in the [LICENSE](./LICENSE) file.