# Go Library - picket-go

## picket-go

The official Picket API Go library. View it on [Github](https://github.com/picketapi/picket-go).

### Installation

```bash
go get -u github.com/picketapi/picket-go
```

### Usage - Quick Start

Use the `picketapi.NewClient` to create the Picket API client. It takes a *secret API key* as a parameter.

```go
import (
	picketapi "github.com/picketapi/picket-go"
)

picket := picketapi.NewClient("YOUR_SECRET_API_KEY")
```

### Nonce

A `nonce` is random value generated by the Picket API to that user must sign to prove ownership a wallet address. The `nonce` function can be used to implement your own wallet authentication flow.

A nonce is unique to a project and wallet address. If a `nonce` doesn't exist for the project and wallet address, Picket will generate a new nonce; otherwise, Picket will return the existing nonce. A nonce is valid for two minutes before self-destructing.

```go
resp, err := picket.Nonce(picketapi.NonceArgs{
		Chain:         "solana",
		WalletAddress: "wAllEtadDresS",
})
fmt.Printf("received nonce: %s", resp.Nonce)
```

### Auth

`auth` is the server-side equivalent of login. `auth` should only be used in a trusted server environment. The most common use-case for `auth` is [linking a wallet to an existing application account](https://docs.picketapi.com/picket-docs/tutorials/link-a-wallet-to-a-web-2.0-account).

```go
resp, err := picket.Auth(picketapi.AuthArgs{
		Chain:         "ethereum",
		WalletAddress: "0x1234567890",
		Signature:     "abcdefghijklmnop",
})
fmt.Printf("received access token: %s", resp.AccessToken)
```

### Authz (Authorize)

{% hint style="info" %}
**Incremental Authorization (Authz)**

To understand the use-cases for using `authz` over `auth`, read about [Incremental Authorization](https://docs.picketapi.com/picket-docs/reference/concepts/incremental-authorization)
{% endhint %}

`authz` stands for authorization. Unlike Auth, which handles both authentication and authorization, Authz only handles authorization. Given an authenticated user's access token and authorization requirements, `authz` will issue a new access token on success (user is authorized) or, on failure, it will return a 4xx HTTP error code.

```go
resp, err := picket.Authz(picketapi.AuthzArgs{
		AccessToken: "aaa.bbb.ccc",
		Requirements: picketapi.AuthorizationRequirements{
			ContractAddress: "0xContract",
			MinTokenBalance: "100",
		},
})
fmt.Printf("received updated access token: %s", resp.AccessToken)
```

### Validate

`validate` validates an access token. `validate` should be called, or manually access token validation should be done, server-side before trusting a request's access token. It's common to move access token validation and decoding logic to a shared middleware across API endpoints. If the access token is valid, validate returns the decoded claims of the access token.

```go
resp, err := picket.Validate(picketapi.ValidateArgs{
		AccessToken: "aaa.bbb.ccc",
		// Authorizatopn args are optional
		Requirements: picketapi.AuthorizationRequirements{
			ContractAddress: "0xContract",
			MinTokenBalance: "100",
		},
})
fmt.Printf("decoded access token: %v", resp)
```

### Verify Token Ownership

If you only want to verify token ownership server side for a given wallet, `tokenOwnership` allows you to do just that.

```go
resp, err := picket.TokenOwnership(picketapi.TokenOwnershipArgs{
		Chain:         "solana",
		WalletAddress: "waLLeTaddrESs",
		Requirements: picketapi.AuthorizationRequirements{
			Collection: "METAPLEX_COLLECTION",
			MinTokenBalance: "3",
		},
})
fmt.Printf("wallet has sufficient tokens: %s", resp.Allowed)
```