mirror of
https://github.com/gravitational/teleport.git
synced 2026-09-24 16:17:11 +08:00
Paul Gottschling
9ff423ab89
Our API getting started guide includes a go snippet that ends with "EOF," which is not a Go keyword. If the reader isn't familiar with Go but wants to follow this guide, the Go compiler will return a syntax error. This change removes the line.
119 lines
3.7 KiB
Plaintext
119 lines
3.7 KiB
Plaintext
---
|
|
title: API Getting Started Guide
|
|
description: Get started working with the Teleport API programmatically using Go.
|
|
---
|
|
|
|
# Getting Started
|
|
|
|
In this getting started guide we will use the Teleport API Go client to connect
|
|
to a Teleport Node configured as an Auth Server.
|
|
|
|
Here are the steps we'll walkthrough:
|
|
|
|
1. Create an API user using a simple role-based authentication method.
|
|
2. Generate credentials for that user.
|
|
3. Create and connect a Go client to interact with Teleport's API.
|
|
|
|
## Prerequisites
|
|
|
|
- Install [Go](https://golang.org/doc/install) (=teleport.golang=)+ and Go development environment.
|
|
- Set up Teleport through one of our [getting started guides](../getting-started.mdx). You can also begin a [free trial](https://goteleport.com/signup/) of Teleport Cloud.
|
|
|
|
## Step 1/3. Create a user
|
|
|
|
(!docs/pages/includes/permission-warning.mdx!)
|
|
|
|
<Admonition type="tip" title="Tip">
|
|
Read [API authorization](./architecture.mdx#authorization) to learn more about defining custom roles for your API client.
|
|
</Admonition>
|
|
|
|
Create a user `api-admin` with the built-in role `editor`:
|
|
|
|
```code
|
|
# Run this directly on your Auth Server unless you are using Teleport Cloud
|
|
# Add a user and login via the Proxy Service
|
|
$ sudo tctl users add api-admin --roles=editor
|
|
```
|
|
|
|
## Step 2/3. Generate client credentials
|
|
|
|
Log in as the newly created user with `tsh`.
|
|
|
|
```code
|
|
# generate tsh profile
|
|
$ tsh login --user=api-admin --proxy=tele.example.com
|
|
```
|
|
|
|
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:
|
|
|
|
```code
|
|
$ mkdir client-demo && cd client-demo
|
|
$ go mod init client-demo
|
|
$ go get github.com/gravitational/teleport/api/client
|
|
```
|
|
|
|
Create a file called `main.go`, modifying the `Addrs` strings as needed:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
|
|
"github.com/gravitational/teleport/api/client"
|
|
)
|
|
|
|
func main() {
|
|
ctx := context.Background()
|
|
|
|
clt, err := client.New(ctx, client.Config{
|
|
Addrs: []string{
|
|
// Teleport Cloud customers should use <tenantname>.teleport.sh
|
|
"tele.example.com:443",
|
|
"tele.example.com:3025",
|
|
"tele.example.com:3024",
|
|
"tele.example.com:3080",
|
|
},
|
|
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("Example success!")
|
|
log.Printf("Example server response: %s", resp)
|
|
log.Printf("Server version: %s", resp.ServerVersion)
|
|
}
|
|
```
|
|
|
|
Now you can run the program and connect the client to the Teleport Auth Server to fetch the server version.
|
|
|
|
```code
|
|
$ go run main.go
|
|
```
|
|
|
|
## Next steps
|
|
|
|
- Learn about [pkg.go.dev](https://pkg.go.dev/github.com/gravitational/teleport/api/client)
|
|
- Learn how to use [the client](https://pkg.go.dev/github.com/gravitational/teleport/api/client#Client)
|
|
- Learn how to [work with credentials](https://pkg.go.dev/github.com/gravitational/teleport/api/client#Credentials)
|
|
- Read about Teleport [API architecture](./architecture.mdx) for an in-depth overview of the API and API clients.
|
|
- Read [API authorization](./architecture.mdx#authorization) to learn more about defining custom roles for your API client.
|
|
- Review the `client` [pkg.go reference documentation](https://pkg.go.dev/github.com/gravitational/teleport/api/client) for more information about working with the Teleport API programmatically.
|
|
- Familiarize yourself with the [admin manual](../setup/admin.mdx) to make the best use of the API.
|