onepassword

README

1Password Go SDK (beta)

❗ The 1Password SDK project is in beta. Future iterations may bring backwards-incompatible changes.

Documentation | Examples

---

The 1Password Go SDK offers programmatic access to your secrets in 1Password with Go. During the beta, you can create, retrieve, update, and delete items and resolve secret references.

🔑 Authentication

1Password SDKs support authentication with 1Password Service Accounts.

Before you get started, create a service account and give it the appropriate permissions in the vaults where the items you want to use with the SDK are saved.

❗ Limitations

1Password SDKs don't yet support using secret references with query parameters, so you can't retrieve file attachments or SSH keys, or get more information about field metadata.

1Password SDKs currently only support operations on text and concealed fields. As a result, you can't edit items that include information saved in other types of fields.

When managing items with 1Password SDKs, you must use unique identifiers (IDs) in place of vault, item, and field names.

🚀 Get started

To use the 1Password Go SDK in your project:

1. Provision your service account token. We recommend provisioning your token from the environment. For example, to export your token to the OP_SERVICE_ACCOUNT_TOKEN environment variable:

   macOS or Linux

   export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
   

   Windows

   $Env:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>"
   

2. Install the 1Password Go SDK in your project:

   go get github.com/1password/onepassword-sdk-go
   

3. Use the Go SDK in your project:

import (
    "context"
    "os"

    "github.com/1password/onepassword-sdk-go"
)

func main() {
    token := os.Getenv("OP_SERVICE_ACCOUNT_TOKEN")

    client, err := onepassword.NewClient(
                context.TODO(),
                onepassword.WithServiceAccountToken(token),
                onepassword.WithIntegrationInfo("My 1Password Integration", "v1.0.0"),
    )
    if err != nil {
	// handle err
    }
    secret, err := client.Secrets.Resolve("op://vault/item/field")
    if err != nil {
        // handle err
    }
    // do something with the secret
}

Inside onepassword.WithIntegrationInfo(...), pass the name of your application and the version of your application as arguments.

Make sure to use secret reference URIs with the syntax op://vault/item/field to securely load secrets from 1Password into your code.

📖 Learn more

• Load secrets with 1Password SDKs
• Manage items with 1Password SDKs
• 1Password SDK concepts

Documentation

Overview

AUTOGENERATED - DO NOT EDIT

AUTOGENERATED - DO NOT EDIT MANUALLY

AUTOGENERATED - DO NOT EDIT MANUALLY

Code generated by typeshare 1.9.2. DO NOT EDIT.

Index

• Constants
• type Client
  • func NewClient(ctx context.Context, opts ...ClientOption) (*Client, error)
• type ClientOption
  • func WithIntegrationInfo(name string, version string) ClientOption
  • func WithServiceAccountToken(token string) ClientOption
• type Item
• type ItemCategory
• type ItemField
• type ItemFieldType
• type ItemSection
• type ItemsAPI
• type ItemsSource
  • func NewItemsSource(inner internal.InnerClient) *ItemsSource
  • func (s ItemsSource) Create(ctx context.Context, item Item) (Item, error)
  • func (s ItemsSource) Delete(ctx context.Context, vaultId string, itemId string) error
  • func (s ItemsSource) Get(ctx context.Context, vaultId string, itemId string) (Item, error)
  • func (s ItemsSource) Update(ctx context.Context, item Item) (Item, error)
• type SecretsAPI
• type SecretsSource
  • func NewSecretsSource(inner internal.InnerClient) *SecretsSource
  • func (s SecretsSource) Resolve(ctx context.Context, secretReference string) (string, error)

Constants

const (
	DefaultIntegrationName    = "Unknown"
	DefaultIntegrationVersion = "Unknown"
)

Types

type Client

type Client struct {
	Secrets SecretsAPI
	Items   ItemsAPI
	// contains filtered or unexported fields
}

Client represents an instance of the 1Password Go SDK client.

func NewClient

func NewClient(ctx context.Context, opts ...ClientOption) (*Client, error)

NewClient returns a 1Password Go SDK client using the provided ClientOption list.

type ClientOption

type ClientOption func(client *Client) error

func WithIntegrationInfo

func WithIntegrationInfo(name string, version string) ClientOption

WithIntegrationInfo specifies the name and version of the integration built using the 1Password Go SDK. If you don't know which name and version to use, use `DefaultIntegrationName` and `DefaultIntegrationVersion`, respectively.

func WithServiceAccountToken

func WithServiceAccountToken(token string) ClientOption

WithServiceAccountToken specifies the [1Password Service Account](https://developer.1password.com/docs/service-accounts) token to use to authenticate the SDK client. Read more about how to get started with service accounts: https://developer.1password.com/docs/service-accounts/get-started/#create-a-service-account

type Item

type Item struct {
	// The item's unique ID
	ID string `json:"id"`
	// The item's title
	Title string `json:"title"`
	// The item's category
	Category ItemCategory `json:"category"`
	// The ID of the vault where the item is saved
	VaultID string `json:"vault_id"`
	// The item's fields
	Fields []ItemField `json:"fields"`
	// The item's sections
	Sections []ItemSection `json:"sections"`
}

Represents a 1Password item.

type ItemCategory

type ItemCategory string

const (
	ItemCategoryLogin                ItemCategory = "Login"
	ItemCategorySecureNote           ItemCategory = "SecureNote"
	ItemCategoryCreditCard           ItemCategory = "CreditCard"
	ItemCategoryCryptoWallet         ItemCategory = "CryptoWallet"
	ItemCategoryIdentity             ItemCategory = "Identity"
	ItemCategoryPassword             ItemCategory = "Password"
	ItemCategoryDocument             ItemCategory = "Document"
	ItemCategoryApiCredentials       ItemCategory = "ApiCredentials"
	ItemCategoryBankAccount          ItemCategory = "BankAccount"
	ItemCategoryDatabase             ItemCategory = "Database"
	ItemCategoryDriverLicense        ItemCategory = "DriverLicense"
	ItemCategoryEmail                ItemCategory = "Email"
	ItemCategoryMedicalRecord        ItemCategory = "MedicalRecord"
	ItemCategoryMembership           ItemCategory = "Membership"
	ItemCategoryOutdoorLicense       ItemCategory = "OutdoorLicense"
	ItemCategoryPassport             ItemCategory = "Passport"
	ItemCategoryRewards              ItemCategory = "Rewards"
	ItemCategoryRouter               ItemCategory = "Router"
	ItemCategoryServer               ItemCategory = "Server"
	ItemCategorySshKey               ItemCategory = "SshKey"
	ItemCategorySocialSecurityNumber ItemCategory = "SocialSecurityNumber"
	ItemCategorySoftwareLicense      ItemCategory = "SoftwareLicense"
	ItemCategoryPerson               ItemCategory = "Person"
	ItemCategoryUnsupported          ItemCategory = "Unsupported"
)

type ItemField

type ItemField struct {
	// The field's ID
	ID string `json:"id"`
	// The field's title
	Title string `json:"title"`
	// The ID of the section containing the field. Designated fields such as usernames and passwords don't need to specify a section.
	SectionID *string `json:"section_id,omitempty"`
	// The type of value stored in the field
	FieldType ItemFieldType `json:"field_type"`
	// The string representation of the field's value
	Value string `json:"value"`
}

Stores a field's title and value.

type ItemFieldType

type ItemFieldType string

const (
	ItemFieldTypeText        ItemFieldType = "Text"
	ItemFieldTypeConcealed   ItemFieldType = "Concealed"
	ItemFieldTypeUnsupported ItemFieldType = "Unsupported"
)

type ItemSection

type ItemSection struct {
	// The section's ID
	ID string `json:"id"`
	// The section's name
	Title string `json:"title"`
}

A section groups together multiple fields in an item.

type ItemsAPI

type ItemsAPI interface {
	// Create a new item
	Create(ctx context.Context, item Item) (Item, error)
	// Get an item by vault and item ID
	Get(ctx context.Context, vaultId string, itemId string) (Item, error)
	// Update an existing item. You can currently only edit text and concealed fields.
	Update(ctx context.Context, item Item) (Item, error)
	// Delete an item.
	Delete(ctx context.Context, vaultId string, itemId string) error
}

ItemsAPI contains all operations the SDK client can perform on 1Password items.

type ItemsSource

type ItemsSource struct {
	internal.InnerClient
}

func NewItemsSource

func NewItemsSource(inner internal.InnerClient) *ItemsSource

func (ItemsSource) Create

func (s ItemsSource) Create(ctx context.Context, item Item) (Item, error)

func (ItemsSource) Delete

func (s ItemsSource) Delete(ctx context.Context, vaultId string, itemId string) error

func (ItemsSource) Get

func (s ItemsSource) Get(ctx context.Context, vaultId string, itemId string) (Item, error)

func (ItemsSource) Update

func (s ItemsSource) Update(ctx context.Context, item Item) (Item, error)

type SecretsAPI

type SecretsAPI interface {
	// Resolve returns the secret the provided secret reference points to.
	// Secret references point to fields in 1Password. They have the following format: op://<vault-name>/<item-name>[/<section-name>]/<field-name>
	// Read more about secret references: https://developer.1password.com/docs/cli/secret-references
	Resolve(ctx context.Context, secretReference string) (string, error)
}

type SecretsSource

type SecretsSource struct {
	internal.InnerClient
}

func NewSecretsSource

func NewSecretsSource(inner internal.InnerClient) *SecretsSource

func (SecretsSource) Resolve

func (s SecretsSource) Resolve(ctx context.Context, secretReference string) (string, error)

Resolve returns the secret the provided secret reference points to. Secret references point to fields in 1Password. They have the following format: op://<vault-name>/<item-name>[/<section-name>]/<field-name> Read more about secret references: https://developer.1password.com/docs/cli/secret-references