boundary/website/content/docs/developing/sdk/authenticate.mdx

---
layout: docs
page_title: SDK - Authenticate
sidebar_title: Authenticate
description: |-
  Boundary SDK authenticate 
---

# Authenticate 

Authenticating to Boundary starts with an [Auth Method](/docs/concepts/domain-model/auth-methods). An auth method provides
the basic identity delegation needed for Boundary to generate a token for a client. There are two primary methods for
authenticating to Boundary:

1. Via an authentication method
1. Via the recovery KMS workflow

We'll cover how to authenticate to Boundary via both of these workflows. 

## Authentication Method

This is the most common way for a client to authenticate to Boundary. To demonstrate this, we'll
use the [authmethods](https://github.com/hashicorp/boundary/tree/main/api/authmethods) library to generate
a valid token for a client in go.

For this example, we're going to use the password auth method. This example assumes there's already
a valid user and an associated account in Boundary for the client to authenticate as. To simplify this 
example, we're assuming you're running a Boundary instance in dev mode, where the default auth method, login name, 
and password are pre-configured. 

First, we need to create a net/http client from the Boundary API and set the address to reach Boundary:

```golang
import github.com/boundary/api

// assumes Boundary in dev mode
const boundaryAddr := "http://localhost:9200"

client, err := api.NewClient(nil)
if err != nil {
  return err
}

client.SetAddr(boundaryAddr)
```

The [auth method client](https://github.com/hashicorp/boundary/blob/main/api/authmethods/authenticate.go) uses a basic `map[string]interface{}` to pass credential information. For this example, 
we assume you're using the password auth method and so we're going to tailor a credentials object
to pass this data as:

```golang
credentials := map[string]interface{}{
  "login_name": "admin",
  "password":   "password",
}
```

Now lets create an auth method client using the base client from above:

```golang
import github.com/boundary/api/authmethods

am := authmethods.NewClient(client)
```

The last thing you'll need is the ID of the auth method in Boundary. You can get this on the CLI 
with:

```bash
$ boundary auth-methods list

Auth Method information:
  ID:             ampw_1234567890
    Description:  Provides initial administrative authentication into Boundary
    Name:         Generated global scope initial auth method
    Type:         password
    Version:      1
```

Note the ID in the output above, we're going to use that in the next step.

We can use the credentials object we created to execute `Authenticate()` on this client:

```golang
at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials)
if err != nil {
  return err
}
```

Lastly, let's update the original client with the token we got from the `Authenticate()` call:

```golang
client.SetToken(at.Item.Token)
```

Putting this all together:

```golang
import (
  github.com/boundary/api
  github.com/boundary/api/authmethods
)

// assumes Boundary in dev mode
const boundaryAddr := "http://localhost:9200"

credentials := map[string]interface{}{
  "login_name": "admin",
  "password":   "password",
}

client, err := api.NewClient(nil)
if err != nil {
  return err
}

client.SetAddr(boundaryAddr)

am := authmethods.NewClient(client)
at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials)
if err != nil {
  return err
}

// pass this client to any other resource specific API resources
client.SetToken(at.Item.Token)
```

## Recovery KMS Workflow

The recovery KMS workflow allows you to use a valid [KMS configuration](/docs/configuration/kms) to generate a token for a Boundary 
client. For this example, we're going to assume you've read the above and know how to get a base Boundary API 
client.

Lets start with a valid KMS configuration for recovery that uses a hard coded AEAD key as the basis. To authenticate with Boundary using this config we're assuming you have a instance of Boundary that declares this as the recovery KMS in the Boundary controller config as well.

```golang
const kmsConfig := `
kms "aead" {
    purpose = "recovery"
    aead_type = "aes-gcm"
    key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
    key_id = "recovery_kms"
}
`
```

Now lets use this config to configure our Boundary API client:

```golang
client.SetRecoveryKmsWrapper(kmsConfig)
```

And finally, execute `Authenticate()`:

```golang
am := authmethods.NewClient(client)
at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials)
if err != nil {
  return err
}

// pass this client to any other resource specific API resources
client.SetToken(at.Item.Token)
```