mirror of
https://github.com/gravitational/teleport.git
synced 2026-11-04 19:12:46 +08:00
99 lines
2.5 KiB
Plaintext
99 lines
2.5 KiB
Plaintext
---
|
|
title: API Getting Started Guide
|
|
description: Getting started with the Teleport API
|
|
---
|
|
|
|
# Getting Started
|
|
|
|
In this getting started guide we will use the Teleport API Go Client to connect to the Teleport Auth server.
|
|
|
|
Here are the steps we'll walk through:
|
|
1. Create an API user
|
|
2. Generate credentials
|
|
3. Create a Go program to demo the client
|
|
|
|
## Prerequisites
|
|
|
|
- Install [Go](https://golang.org/doc/install) (=teleport.golang=)+ and Setup Go Dev Environment
|
|
- Set up Teleport with the [Getting Started Guide](../../getting-started.mdx)
|
|
|
|
## 1/3 Create a User
|
|
|
|
Create a new user for the client to impersonate.
|
|
|
|
```bash
|
|
# Run this directly on your auth server
|
|
# Add user and login via web proxy
|
|
tctl users add api-user --roles=admin
|
|
```
|
|
|
|
<Admonition type="note">
|
|
It is generally best practice to create custom roles for each client user. See [API authorization](./architecture.mdx#authorization).
|
|
</Admonition>
|
|
|
|
## 2/3 Generate Client Credentials
|
|
|
|
Login as the newly created user with `tsh`.
|
|
|
|
```bash
|
|
# generate tsh profile
|
|
tsh login --user=api-user
|
|
```
|
|
|
|
The [profile Credentials loader](https://pkg.go.dev/github.com/gravitational/teleport/api/client#LoadProfile)
|
|
will automatically retrieve Credentials from the current profile in the next step.
|
|
|
|
## Step 3/3 Create a go project
|
|
|
|
Set up a new [Go module](https://golang.org/doc/tutorial/create-module) and import the `client` package:
|
|
|
|
```bash
|
|
mkdir client-demo && cd client-demo
|
|
go mod init client-demo
|
|
go get github.com/gravitational/teleport/api/client
|
|
```
|
|
|
|
Add the following code to a new `main.go` file.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
|
|
"github.com/gravitational/teleport/api/client"
|
|
)
|
|
|
|
func main() {
|
|
ctx := context.Background()
|
|
|
|
clt, err := client.New(ctx, client.Config{
|
|
Credentials: []client.Credentials{
|
|
client.LoadProfile("", ""),
|
|
},
|
|
})
|
|
if err != nil {
|
|
log.Fatalf("failed to create client: %v", err)
|
|
}
|
|
defer clt.Close()
|
|
|
|
resp, err := clt.Ping(ctx)
|
|
if err != nil {
|
|
log.Fatalf("failed to ping server: %v", err)
|
|
}
|
|
log.Printf("server version: %s", resp.ServerVersion)
|
|
}
|
|
```
|
|
|
|
Now you can run the program which will connect the client to the Teleport Auth server and fetch the server version.
|
|
|
|
```bash
|
|
go run main.go
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- Read about the [API architecture](./architecture.mdx) for a more in depth look at the API client.
|
|
- Visit the `client` package's [pkg.go.dev](https://pkg.go.dev/github.com/gravitational/teleport/api/client) for easy to navigate code oriented documentation.
|
|
- Familiarize yourself with the [admin manual](../../admin-guide.mdx) to make the best use of the API. |