connect-sdk-go

README

1Password Connect Go SDK

The 1Password Connect Go SDK provides access to the 1Password Connect API hosted on your infrastructure. The library is intended to be used by your applications, pipelines, and other automations to simplify accessing items stored in your 1Password vaults.

Installation

go get github.com/1Password/connect-sdk-go

Usage

Environment Variables

Variable	Description	Feature
OP_CONNECT_TOKEN	The API token to be used to authenticate the client to a 1Password Connect API.	API Client
OP_CONNECT_HOST	The hostname of the 1Password Connect API	API Client
OP_VAULT	If the opvault tag is not set the client will default to this vault UUID	Unmarshalling

Creating an API Client

connect.Client instances require two pieces of configuration. A token and a hostname. There are three constructor methods provided by this library for creating your client.

• connect.NewClient – Accepts a hostname and a token value.
• connect.NewClientFromEnvironment – Fetches the hostname and token value from the environment
• connect.NewClientWithUserAgent – Accepts a hostname, a token value, and a custom User-Agent string for identifying the client to the 1Password Connect API

Unmarshalling into a Struct

Users can define tags on a struct and have the connect.Client unmarshall item data directly in them. Supported field tags are:

• opvault – The UUID of the vault the item should come from
• opitem – The title of the Item
• opsection - The section where the required field is located
• opfield – The item field whose value should be retrieved

All retrieved fields require at least the opfield and opitem tags, while all retrieved items require the opitem tag. Additionally, a custom vault can be specified by setting the opvault tag. In case this is not set, the SDK will use the value of the OP_VAULT environment variable as the default UUID. If a field is within a section, the opsection tag is required as well. Please note that one cannot retrieve a section in itself.

Example Struct

This example struct will retrieve 3 fields from one item and a whole item from another vault:

package main

import (
	"github.com/1Password/connect-sdk-go/connect"
	"github.com/1Password/connect-sdk-go/onepassword"
)

type Config struct {
	Username string           `opitem:"Demo TF Database" opfield:"username"`
	Password string           `opitem:"Demo TF Database" opfield:"password"`
        Host     string           `opitem:"Demo TF Database" opsection:"details" opfield:"hostname"`
	APIKey   onepassword.Item `opvault:"7vs66j55o6md5btwcph272mva4" opitem:"API Key"`
}

func main() {
	client, err := connect.NewClientFromEnvironment()
	if err != nil {
		panic(err)
	}
    	c := Config{}
	err = client.LoadStruct(&c)
}

Additionally, fields of the same item can be added to a struct at once, without needing to specify the opitem or opvault tags:

package main

import "github.com/1Password/connect-sdk-go/connect"


type Config struct {
	Username string     `opfield:"username"`
	Password string     `opfield:"password"`
}

func main () {
	client, err := connect.NewClientFromEnvironment()
    	if err != nil {
		panic(err)
	}
	c := Config{}
	err = client.LoadStructFromItemByTitle(&c, "Demo TF Database", "7vs66j55o6md5btwcph272mva4") // retrieve using item title
        err = client.LoadStructFromItem(&c, "4bc73kao58g2usb582ndn3w4", "7vs66j55o6md5btwcph272mva4") // retrieve using item uuid
}

Model Objects

The onepassword.Item model represents Items and onepassword.Vault represent Vaults in 1Password

Item CRUD

The connect.Client also supports methods for:

• listing Vaults
• listing items in a Vault
• searching by Item Title
• Retrieving Item by Vault and Item UUID
• Creating Items in a Vault
• Updating Items
• Deleting Items
• Retrieving and Downloading Files

Errors

All errors returned by Connect API are unmarshalled into a onepassword.Error struct:

type Error struct {
    StatusCode int    `json:"status"`
    Message    string `json:"message"`
}

Details of the errors can be accessed by using errors.As():

_, err := client.GetVaults()
if err != nil{
    var opErr *onepassword.Error
    if errors.As(err, &opErr){
        fmt.Printf("message=%s, status code=%d\n",
            opErr.Message,
            opErr.StatusCode,
        )
    }
}

Development

Building

To build all packages run

go build ./...

Running Tests

To run all tests and see test coverage run

go test -v ./... -cover

Security

1Password requests you practice responsible disclosure if you discover a vulnerability.

Please file requests via BugCrowd.

For information about security practices, please visit our Security homepage.