Teleport

API Getting Started Guide

OpenSource
Enterprise
Cloud

Improve

In this getting started guide we will use the Teleport API Go client to connect to a Teleport Auth Service.

Here are the steps we'll walkthrough:

Create an API user using a simple role-based authentication method.
Generate credentials for that user.
Create and connect a Go client to interact with Teleport's API.

Prerequisites

Install Go 1.20+ and Go development environment.

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 13.0.3.
```
tctl version
Teleport v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```
See Installation for details.

A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 13.0.3, which you can download by visiting your Teleport account.
```
tctl version
Teleport Enterprise v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

Make sure you can connect to Teleport. Log in to your cluster using tsh, then use tctl remotely:
```
tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  13.0.3
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
You can run subsequent tctl commands in this guide on your local machine.
For full privileges, you can also run tctl commands on your Auth Service host.

Step 1/3. Create a user

When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:

Avoid using sudo in production environments unless it's necessary.
Create new, non-root, users and use test instances for experimenting with Teleport.
Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
Follow the "Principle of Least Privilege" (PoLP). Don't give users permissive roles when giving them more restrictive roles will do instead. For example, assign users the built-in access,editor roles.
When joining a Teleport resource service (e.g., the Database Service or Application Service) to a cluster, save the invitation token to a file. Otherwise, the token will be visible when examining the teleport command that started the agent, e.g., via the history command on a compromised system.

Tip

Read API authorization to learn more about defining custom roles for your API client.

Create a user api-admin with the built-in role editor:

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

generate tsh profile
tsh login --user=api-admin --proxy=tele.example.com

The Profile Credentials loader 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 and import the client package:

mkdir client-demo && cd client-demo
go mod init client-demo
go get github.com/gravitational/teleport/api/client

API Version

To ensure compatibility, you should use a version of Teleport's API library that matches the major version of Teleport running in your cluster.

To find the pseudoversion appropriate for a go.mod file for a specific git tag, run the following command from the teleport repository:

go list -f '{{.Version}}' -m "github.com/gravitational/teleport/[email protected]$(git rev-parse v12.1.0)"
v0.0.0-20230307032901-49a6de744a3a

Create a file called main.go, modifying the Addrs strings as needed:

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.

go run main.go

Next steps

Learn about pkg.go.dev
Learn how to use the client
Learn how to work with credentials
Read about Teleport API architecture for an in-depth overview of the API and API clients.
Read API authorization to learn more about defining custom roles for your API client.
Review the client pkg.go reference documentation for more information about working with the Teleport API programmatically.
Familiarize yourself with the admin manual to make the best use of the API.

Have a suggestion or can’t find something?

IMPROVE THE DOCS