Go SDK

Use the Go SDK, github.com/unkeyed/sdks/api/go/v3 (current release ), to call the Unkey API from Go. The older v1 and v2 module paths are no longer updated.

You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys, and pass it as Authorization: Bearer <root key>. See Permission reference for every permission.

Install

go get github.com/unkeyed/sdks/api/go/v3

It needs a recent Go toolchain (currently Go 1.25).

Construct the client

import (
	unkey "github.com/unkeyed/sdks/api/go/v3"
)

client := unkey.New(
	unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
)

WithSecurity sets your root key. To change retries for every call, add unkey.WithRetryConfig(retry.Config{...}). For one call, pass operations.WithRetries(...) as the last argument. Request and response types are in github.com/unkeyed/sdks/api/go/v3/models/components, and typed errors in .../models/apierrors.

Verify a key

import (
	"errors"

	"github.com/unkeyed/sdks/api/go/v3/models/components"
)

res, err := client.Keys.VerifyKey(ctx, components.V2KeysVerifyKeyRequestBody{
	Key:         "prod_abc123",
	Permissions: unkey.String("documents.read"), // optional permission query
})
if err != nil {
	return err
}
if res.V2KeysVerifyKeyResponseBody == nil {
	return errors.New("unkey: empty response body")
}

data := res.V2KeysVerifyKeyResponseBody.Data
if !data.Valid {
	// data.Code says why: NOT_FOUND, DISABLED, EXPIRED, RATE_LIMITED, ...
}

The response field, here V2KeysVerifyKeyResponseBody, is a pointer, so check it for nil even when err is nil. Optional request fields are pointers or slices. Use helpers such as unkey.String and unkey.Bool for pointer values. An invalid key is a successful call with Valid false, not an error. The meaning of each field is covered in Verifying keys and the schema in keys.verifyKey.

Create a key

res, err := client.Keys.CreateKey(ctx, components.V2KeysCreateKeyRequestBody{
	APIID:       "api_1234abcd",
	Prefix:      unkey.String("prod"),
	Name:        unkey.String("Payment service"),
	ExternalID:  unkey.String("user_42"),
	Permissions: []string{"documents.read"},
	Enabled:     unkey.Bool(true),
})
if err != nil {
	return err
}

created := res.V2KeysCreateKeyResponseBody.Data
fmt.Println(created.KeyID)
fmt.Println(created.Key) // returned once; store it or hand it to the user now

ByteLength, Meta, Roles, Expires, Credits, Ratelimits, and Recoverable are the remaining fields. Creating keys explains them and keys.createKey lists the schema.

Apply a rate limit

res, err := client.Ratelimit.Limit(ctx, components.V2RatelimitLimitRequestBody{
	Namespace:  "email.send",
	Identifier: "user_42",
	Limit:      10,
	Duration:   60_000, // milliseconds
})
if err != nil {
	return err
}
if !res.V2RatelimitLimitResponseBody.Data.Success {
	// Data.Remaining and Data.Reset (Unix ms) tell the caller when to retry
}

The endpoint is ratelimit.limit.

Create a deployment

The client covers Compute too. Name the project, app, and environment, and optionally set the source with one of Oci, Git, or Deployment. Leave all three out to use the app’s default:

res, err := client.Deployments.CreateDeploymentV3(ctx, components.V3DeploymentsCreateDeploymentRequestBody{
	Project:     "my-project",
	App:         "api",
	Environment: "production",
	Oci:         &components.DeploymentSourceOCI{Image: "ghcr.io/acme/api:v1.0.0"},
})
if err != nil {
	return err
}
fmt.Println(res.V3DeploymentsCreateDeploymentResponseBody.Data.DeploymentID)

The endpoint is deployments.createDeploymentV3. Don’t use the CreateDeployment method. It calls the deprecated v2 endpoint. For projects, apps, and environments, see Projects, apps, and environments.

Handle errors

Every method returns a response or an error, never both. API errors have a type per status that you can match with errors.As. Anything else is an *apierrors.APIError.

import (
	"errors"

	"github.com/unkeyed/sdks/api/go/v3/models/apierrors"
)

res, err := client.Keys.GetKey(ctx, components.V2KeysGetKeyRequestBody{KeyID: "key_1234abcd"})
if err != nil {
	var notFound *apierrors.NotFoundErrorResponse
	var unauthorized *apierrors.UnauthorizedErrorResponse
	var apiErr *apierrors.APIError
	switch {
	case errors.As(err, &notFound):
		fmt.Println("not found:", notFound.Error_.GetDetail())
	case errors.As(err, &unauthorized):
		fmt.Println("check the root key:", unauthorized.Error_.GetDetail())
	case errors.As(err, &apiErr):
		fmt.Println(apiErr.StatusCode, apiErr.Message)
	default:
		return err // transport failure
	}
}

The typed errors are BadRequestErrorResponse (400, whose Error_ is a components.BadRequestErrorDetails with a per-field GetErrors() list), UnauthorizedErrorResponse (401), ForbiddenErrorResponse (403), NotFoundErrorResponse (404), ConflictErrorResponse (409), GoneErrorResponse (410), PreconditionFailedErrorResponse (412), UnprocessableEntityErrorResponse (422), TooManyRequestsErrorResponse (429), InternalServerErrorResponse (500), and ServiceUnavailableErrorResponse (503). Each endpoint page in the API reference, for example keys.getKey, lists which ones apply.

SDKs

TypeScript

Install

Construct the client

Verify a key

Create a key

Apply a rate limit

Create a deployment

Handle errors

Next steps

The unkey CLI

API reference

​Install

​Construct the client

​Verify a key

​Create a key

​Apply a rate limit

​Create a deployment

​Handle errors

​Next steps

The unkey CLI

API reference

Install

Construct the client

Verify a key

Create a key

Apply a rate limit

Create a deployment

Handle errors

Next steps