# Access REST APIs With Teleport Application Access

The Teleport Application Service can be used to access applications' (REST or Teleport's own gRPC) APIs with tools like [curl](https://man7.org/linux/man-pages/man1/curl.1.html) or Postman.

---

NON-HTTP API SUPPORT

Use [TCP application access](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/tcp.md) for non-HTTP APIs (like gRPC).

---

## Prerequisites

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

* For simplicity's sake, we'll use Grafana running in a [Docker container](https://grafana.com/docs/grafana/latest/installation/docker/) and execute API queries against it. You can launch Grafana too with a single Docker command:

  ```
  $ docker run -d -p 3000:3000 grafana/grafana
  ```

  Connect Grafana to your Teleport cluster by adding the following section in the Teleport App Service YAML configuration file:

  ```
  app_service:
    enabled: true
    apps:
    - name: "grafana"
      description: "Test Grafana server"
      uri: "http://localhost:3000"
      labels:
        "env": "dev"

  ```

## Accessing the API

Log into your Teleport cluster and view available applications:

```
$ tsh login --proxy=teleport.example.com
$ tsh apps ls

Application Description         Public Address               Labels
----------- ------------------- ---------------------------- -------
grafana     Test Grafana server grafana.teleport.example.com env=dev
```

Retrieve short-lived X.509 certificate for the application:

```
$ tsh apps login grafana
Logged into app grafana. Example curl command:

$ curl \
  --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \
  --key /Users/alice/.tsh/keys/teleport.example.com/alice \
  https://grafana.teleport.example.com:3080
```

The login message shows an example `curl` command you can run to call the target application's API through Teleport App Access.

---

CA AND KEY PAIR FILES

Note the paths to your user's certificate/key pair in the command - `curl` will use a client certificate to authenticate with Teleport.

The Teleport Proxy Service is usually configured with a wildcard certificate issued by a public certificate authority such as Let's Encrypt. If you are running a self-hosted Teleport cluster, and your Teleport Proxy Service has been configured to use a self-signed certificate instead, you will need to include it in your `curl` command using `--cacert <path>`.

---

As Grafana's API requires authentication, let's update the `curl` command to provide basic auth information using default Grafana username/password and call its `/api/users` endpoint:

```
$ curl --user admin:admin \
  --cert /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem \
  --key /Users/alice/.tsh/keys/teleport.example.com/alice \
    https://grafana.teleport.example.com:3080/api/users

[{"id":1,"name":"","login":"admin","email":"admin@localhost","avatarUrl":"/avatar/46d229b033af06a191ff2267bca9ae56","isAdmin":true,"isDisabled":false,"lastSeenAt":"2021-03-18T17:25:59Z","lastSeenAtAge":"\u003c 1m","authLabels":[]}]
```

The app's X.509 certificate will expire on its own after the TTL allowed by your user's role. You can also remove it explicitly:

```
$ tsh apps logout
Logged out of app "grafana"
```

## Application information

```
$ tsh apps config
```

shows current app URI and paths to the secrets.

This is useful when configuring CLI tools (such as `curl`) or GUI tools (such as Postman).

Let's print the app information in a table format:

```
$ tsh apps config

Name:      grafana
URI:       https://grafana.teleport.example.com:3080
CA:        /Users/alice/.tsh/keys/teleport.example.com/certs.pem
Cert:      /Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem
Key:       /Users/alice/.tsh/keys/teleport.example.com/alice
```

We can also provide different `--format` values to print specific parts of the app configuration:

```
$ tsh apps config --format=uri
https://grafana-root.gravitational.io:3080

$ tsh apps config --format=ca
/Users/alice/.tsh/keys/teleport.example.com/certs.pem

$ tsh apps config --format=cert
/Users/alice/.tsh/keys/teleport.example.com/alice-app/cluster-name/grafana-x509.pem

$ tsh apps config --format=key
/Users/alice/.tsh/keys/teleport.example.com/alice
```

This can be useful in automation for simple templating e.g. to construct an appropriate `curl` command. Using our Grafana `/api/users` example above:

```
$ curl --user admin:admin \
  --cert $(tsh apps config --format=cert) \
  --key $(tsh apps config --format=key) \
    $(tsh apps config --format=uri)/api/users
```