---
title: API Architecture
description: Architectural overview of the Teleport gRPC API.
---

## Authentication

The Auth API uses mTLS to authenticate a client-server connection. Therefore, the client must provide
TLS certificates signed by the Auth server to access the API. These are easy to create and provide using
[Credential loaders](#credentials).

## Authorization

The client certificates signed by the Auth server will be associated with a specific user. This user will
be used to authorize API requests made by the client.

It is recommended to make a new user and role for each client. This makes it easier to track client actions, 
as well as carefully control client permissions.

For example, if your client needs to use `client.GetRole()`, the user must have permission to perform the `read` 
action on the `role` resource. You should create a user and role with the minimum permissions required.

(!docs/pages/includes/permission-warning.mdx!)

```code
# Copy and Paste the below and run on the Teleport Auth server.
cat > api-role.yaml <<EOF
kind: role
metadata:
  name: api-role
spec:
  allow:
    rules:
      - resources: ['role']
        verbs: ['read']
  deny:
    node_labels:
      '*': '*'
version: v5
EOF
# Create role
tctl create -f api-role.yaml
# Add user and login via web proxy
tctl users add api-user --roles=api-role
```

See our [roles](../access-controls/reference.mdx#roles) documentation for more details
on role based access control.

## Credentials

The Teleport Go client uses Credentials to gather and hold TLS certificates, connect 
to proxy servers over SSH, and perform some other actions.

Credentials are created by using Credential loaders, which gather certificates and data 
generated by [Teleport CLIs](../reference/cli.mdx).

Since there are several Credential loaders to choose from with distinct benefits, here's a quick breakdown:
 - Profile Credentials are the easiest to get started with. All you have to do is log in to your device with `tsh login`. Your Teleport proxy address and credentials will automatically be located and used.
 - IdentityFile Credentials are the most well-rounded in terms of usability, functionality,
   and customizability. Identity files can be generated through `tsh login` or `tctl auth sign`,
   making them ideal for both long-lived proxy and auth server connections.
 - Key Pair Credentials have a much simpler implementation than the first two Credentials listed and may feel more familiar. These are good for authenticating clients hosted directly on the auth server.
 - TLS Credentials leave everything up to the client user. This is mostly used internally, but some advanced users may find it useful.

Here are some more specific details to differentiate them by:

| Type | Profile Credentials | Identity Credentials | Key Pair Credentials | TLS Credentials |
| - | - | - | - | - | 
| Ease of use | Easy | Easy | Medium | Hard | 
| Supports long-lived certificates | Yes, but must be configured on server side | Yes | Yes | Yes | 
| Supports SSH connections | Yes | Yes (6.1+) | No | No | 
| Automatic Proxy Address discovery | Yes | No | No | No | 
| CLI used | tsh | tctl/tsh | tctl | - | 
| Available in | 6.1+ | 6.0+ | 6.0+ | 6.0+ | 

See the [Credentials type](https://pkg.go.dev/github.com/gravitational/teleport/api/client#Credentials)
on pkg.go.dev for more information and examples for Credentials and Credential Loaders.

## Client connection

The API client makes requests through an open connection to the Teleport Auth server.

If the Auth server is isolated behind a [Proxy Server](../architecture/proxy.mdx), a reverse
tunnel connection can be made using SSH certificates signed by the auth server. You can either
provide the server's reverse tunnel address directly or provide the web proxy address and have
the client automatically retrieve the reverse tunnel address.

<Admonition type="note">
  While all Credential loaders support mTLS connections, only some support SSH connections (see the chart above).
</Admonition>

Take a look at this client constructor [example](https://pkg.go.dev/github.com/gravitational/teleport/api/client#example-New)
to see what these connection options look like.