unkey-go

unkey-go is a Go client for unkey - a simple, secure, and open-source API key management service.

Get started with unkey & check the official docs for more information.

Installation

To use the unkey-go SDK in your Go project, you can simply import it using Go modules:

go get github.com/WilfredAlmeida/unkey-go

Usage

The APIs are based on the offcial API Documentation. The parameters are same, their initial letter is capitalised.

Examples

Verify Key

package main

import (
    "fmt"

    unkey "github.com/WilfredAlmeida/unkey-go/features"
)

func main() {
    apiKey := "key_3ZZ7faUrkfv1YAhffAcnKW74"

    response, err := unkey.KeyVerify(apiKey)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    if response.Valid {
        fmt.Println("Key is valid")
    } else {
        fmt.Println("Key is invalid")
    }
}

Note: See the structs reference for more information on the response body for KeyVerify

Create Key

package main

import (
    "fmt"

    unkey "github.com/WilfredAlmeida/unkey-go/features"
)

func main() {
    // Prepare the request body
    request := unkey.KeyCreateRequest{
        APIId:      "your-api-id",
        Prefix:     "your-prefix",
        ByteLength: 16,
        OwnerId:    "your-owner-id",
        Meta:       map[string]string{"key": "value"},
        Expires:    0,
        Remaining:  0,
        RateLimit: unkey.KeyCreateRateLimit{
            Type:           "fast",
            Limit:          100,
            RefillRate:     10,
            RefillInterval: 60,
        },
    }

    // Provide the authentication token
    authToken := "your-auth-token"

    // Call the KeyCreate function
    response, err := unkey.KeyCreate(request, authToken)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    // Process the response
    fmt.Println("Key:", response.Key)
    fmt.Println("Key ID:", response.KeyId)
}

Note: Pass the optional & required parameters as per the official API docs. See the structs reference for more information on the request body for KeyCreate

Revoke Key

package main

import (
    "fmt"

    unkey "github.com/WilfredAlmeida/unkey-go/features"
)

func main() {
    // Specify the key ID to revoke
    keyID := "your-key-id"

    // Provide the authentication token
    authToken := "your-auth-token"

    // Call the RevokeKey function
    success, err := unkey.RevokeKey(keyID, authToken)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    // Process the response
    if success {
        fmt.Println("Key revoked successfully")
    } else {
        fmt.Println("Failed to revoke key")
    }
}

Note: The API returns {} as a success response for revkoking key. For user convenience, unkey-go returns boolean

Update Key

package main

import (
    "fmt"

    unkey "github.com/WilfredAlmeida/unkey-go/features"
)

func main() {

    // The API for update has optional params. To determine which params to update, a custome type is made which mimics the behaviour of `undefined`/`null`.
    // To update, define a object in the following manner & set the value for the fields you want to update following on.

    keyUpdateReq := unkey.KeyUpdateRequest{
        KeyId: "someKey",
        Name: unkey.NullableField[string]{Defined: false, Value: new(string)},
        OwnerId: unkey.NullableField[string]{Defined: false, Value: nil},
        Meta: unkey.NullableField[map[string]interface{}]{Defined: false, Value: new(map[string]interface{})},
        Expires: unkey.NullableField[int64]{Defined: false, Value: new(int64)},
        Ratelimit: unkey.NullableField[unkey.RateLimitSchema]{Defined: false, Value: nil},
        Remaining: unkey.NullableField[int64]{Defined: false, Value: new(int64)},
    }

    // Set the value for Name
    keyUpdateReq.Name.Defined = true
    *keyUpdateReq.Name.Value = "John Doe"

    // Set the value for Meta
    keyUpdateReq.Meta.Defined = true
    metaData := map[string]interface{}{
        "field1": "value1",
        "field2": 42,
    }
    *keyUpdateReq.Meta.Value = metaData

    response, err := features.KeyUpdate("someKey",keyUpdateReq, os.Getenv("AUTH_TOKEN"))
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Printf("Response: %+v\n", response)

}

Get API Information

package main

import (
    "fmt"

    unkey "github.com/WilfredAlmeida/unkey-go/features"
)

func main() {
    response, err := features.APIGet("API_ID","AUTH_TOKEN")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Printf("Response: %+v\n", response)
}

Get List Keys

package main

import (
    "fmt"

    unkey "github.com/WilfredAlmeida/unkey-go/features"
)

func main() {
    response, err := features.APIListKeys("API_ID","AUTH_TOKEN")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Printf("Response: %+v\n", response)
}

Structs Reference

The structs used in code for you to get a better idea of the request & response bodies.

KeyVerify

type ratelimitResponse struct {
    Limit     int64 `json:"limit"`
    Remaining int64 `json:"remaining"`
    Reset     int64 `json:"reset"`
}

type KeyVerifyResponse struct {
    Valid       bool                   `json:"valid"`
    OwnerId     string                 `json:"ownerId,omitempty"`
    Meta        map[string]interface{} `json:"meta,omitempty"`
    Expires     int64                  `json:"expires,omitempty"`
    Remaining   int64                  `json:"remaining,omitempty"`
    Ratelimit   *ratelimitResponse     `json:"ratelimit,omitempty"`
    Code        string                 `json:"code,omitempty"`
    Enabled     bool                   `json:"enabled"`
    Environment string                 `json:"environment"`
    KeyId       string                 `json:"keyId"`
    Name        string                 `json:"name"`
    Permissions []string               `json:"permissions"`
}

KeyCreate

type KeyCreateRequest struct {
    APIId      string             `json:"apiId"`
    Prefix     string             `json:"prefix"`
    ByteLength int                `json:"byteLength"`
    OwnerId    string             `json:"ownerId"`
    Meta       Meta               `json:"meta"`
    Expires    int64              `json:"expires"`
    Remaining  int                `json:"remaining"`
    RateLimit  KeyCreateRateLimit `json:"ratelimit"`
}

type Meta map[string]string

type KeyCreateRateLimit struct {
    Type           string `json:"type"`
    Limit          int    `json:"limit"`
    RefillRate     int    `json:"refillRate"`
    RefillInterval int    `json:"refillInterval"`
}

type KeyCreateResponse struct {
    Key   string `json:"key"`
    KeyId string `json:"keyId"`
}

KeyUpdate

type NullableField[T any] struct {
    Defined bool
    Value   *T
}

func (m *NullableField[T]) UnmarshalJSON(data []byte) error {
    m.Defined = true
    return json.Unmarshal(data, &m.Value)
}

type RateLimitSchema struct {
    Type           string `json:"type" validate:"required"`
    Limit          int64  `json:"limit" validate:"required"`
    RefillRate     int64  `json:"refillRate" validate:"required"`
    RefillInterval int64  `json:"refillInterval" validate:"required"`
}

type KeyUpdateRequest struct {
    KeyId     string                         `json:"keyId" validate:"required"`
    Name      NullableField[string]          `json:"name"`
    OwnerId   NullableField[string]          `json:"ownerId"`
    Meta      NullableField[map[string]any]  `json:"meta"`
    Expires   NullableField[int64]           `json:"expires"`
    Ratelimit NullableField[RateLimitSchema] `json:"ratelimit"`
    Remaining NullableField[int64]           `json:"remaining"`
}

APIGet

type APIGetResponse struct {
    ID          string `json:"id"`
    Name        string `json:"name"`
    WorkspaceID string `json:"workspaceId"`
}

APIListKeys

type Key struct {
    ID          string            `json:"id,omitempty"`
    APIID       string            `json:"apiId,omitempty"`
    WorkspaceID string            `json:"workspaceId,omitempty"`
    Start       string            `json:"start,omitempty"`
    CreatedAt   int64             `json:"createdAt,omitempty"`
    Expires     *int64            `json:"expires,omitempty"`
    Ratelimit   ratelimitResponse `json:"ratelimit,omitempty"`
}

type APIListKeysResponse struct {
    Keys  []Key `json:"keys,omitempty"`
    Total int   `json:"total,omitempty"`
}

Note: ratelimitResponse is defined in KeyVerify struct reference

Contributing

Refer the CONTRIBUTING.md file for more information.