# 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.

## How it works

The Teleport Auth Service exposes a gRPC API that allows client tools to manage backend resources. `tctl`, the Teleport Kubernetes Operator, and the Teleport Terraform provider use this API, and you can write custom tools to manage API resources or subscribe to Teleport audit events.

Teleport API clients authenticate to Teleport using TLS credentials. In this guide, we show you how to load the TLS credentials that the Auth Service provides to you after you log in using `tsh`.

## Prerequisites

- Install [Go](https://golang.org/doc/install) 1.25.9+ and Go development environment.

* A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md).

* The `tctl` and `tsh` clients.

  Installing `tctl` and `tsh` clients

  1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

     ```
     $ TELEPORT_DOMAIN=teleport.example.com:443
     $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
     ```

  2. Follow the instructions for your platform to install `tctl` and `tsh` clients:

     **Mac**

     Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients:

     ```
     $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
     ```

     In Finder double-click the `pkg` file to begin installation.

     ---

     DANGER

     Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

     ---

     **Windows - Powershell**

     ```
     $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip
     Unzip the archive and move the `tctl` and `tsh` clients to your %PATH%
     NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
     Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
     ```

     **Linux**

     All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md).

     ```
     $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz
     $ cd teleport
     $ sudo ./install
     Teleport binaries have been copied to /usr/local/bin
     ```

- 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, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username:
  ```
  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  Cluster  teleport.example.com
  Version  19.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](https://goteleport.com/docs/reference/architecture/api-architecture.md) 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](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:

```
$ 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: %v", resp)
	log.Printf("Server version: %s", resp.ServerVersion)
}

```

Now you can run the program and connect the client to the Teleport Auth Service to fetch the server version.

```
$ 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](https://goteleport.com/docs/reference/architecture/api-architecture.md) for an in-depth overview of the API and API clients.
- Read [API authorization](https://goteleport.com/docs/reference/architecture/api-architecture.md) 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](https://goteleport.com/docs/.md) to make the best use of the API.