Skip to main content
Version: 17.x (unreleased)

API Getting Started Guide

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.22+ and Go development environment.

  • A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example: 
    $ tsh login --proxy=teleport.example.com --user=email@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  17.0.0-dev
    # CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Create a user​

Best practices for production security

When running Teleport in production, you should adhere to the following best practices to avoid security incidents:

  • 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. Don't give users permissive roles when more a restrictive role will do. For example, don't assign users the built-in access,editor roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions.
  • When you enroll Teleport resources—for example, new databases or applications—you should save the invitation token to a file. If you enter the token directly on the command line, a malicious user could view it by running the history command on a compromised system.

You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.

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:

$ tctl users add api-admin --roles=editor

Step 2/3. Generate client credentials​

Log in as the newly created user with tsh.

# 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/api@$(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​