> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/how-it-works/identity-and-access.md).

# Identity and Access

Terrakube separates **who you are** (authentication) from **what you can do** (authorization).

### Who can sign in

| Method                     | Use it for                                                  | Page                                                                                           |
| -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Single sign-on through Dex | People using the UI                                         | [User Management](/2.34.0/getting-started/user-management.md)                                  |
| Personal access token      | A person's CLI or scripts. Inherits that user's permissions | [API Tokens](/2.34.0/set-up/organizations/api-tokens.md)                                       |
| Team token                 | Shared automation. Inherits the team's permissions          | [API Tokens](/2.34.0/set-up/organizations/api-tokens.md)                                       |
| `terraform login`          | The Terraform CLI against the API and registry              | [CLI-driven Workflow](/2.34.0/run-terraform/workspaces/cli-driven-workflow.md#terraform-login) |
| Federated credential       | CI jobs and workloads without a stored token                | [Federated Identity](/2.34.0/set-up/organizations/federated-identity.md)                       |

### What a user can do

Access is granted to **teams**, at three levels. A permission at a wider level applies to everything below it.

```mermaid
flowchart TD
    O[Organization team<br/>role or permission flags] --> Pj[Project access]
    Pj --> W[Workspace access]
```

A team has a role (`admin`, `write`, `plan`, `read`) or, with the `custom` role, individual permissions such as managing state, modules, providers, VCS, templates or policies. See [Team Management](/2.34.0/set-up/organizations/team-management.md), [Project Team Access](/2.34.0/set-up/projects/team-access.md) and [Workspace Team Access](/2.34.0/run-terraform/workspaces/team-access.md).

### How a run authenticates to your cloud

[Dynamic provider credentials](/2.34.0/run-terraform/workspaces/dynamic-provider-credentials.md) let a run assume a cloud role without a stored secret.

```mermaid
sequenceDiagram
    participant E as Executor (run)
    participant API as Terrakube API
    participant C as Cloud provider<br/>(AWS, Azure, GCP, Vault)

    E->>API: request identity token for this run
    API-->>E: JWT signed by Terrakube<br/>(sub = organization:…:workspace:…)
    E->>C: exchange JWT for short-lived credentials
    C->>API: fetch public keys (JWKS)
    API-->>C: Terrakube public key
    C-->>E: temporary credentials
    E->>C: terraform plan / apply
```

The cloud provider trusts Terrakube's public key and matches claims such as the organization, workspace and project in its trust policy. Terrakube must therefore be reachable by the cloud provider on its public JWKS endpoints.

### How `terraform login` works

```mermaid
sequenceDiagram
    actor U as User
    participant T as terraform login
    participant API as Terrakube API (OAuth broker)
    participant D as Dex
    T->>API: discover login endpoints
    T->>U: open browser
    U->>API: authorize (PKCE)
    API->>D: sign in
    D-->>API: identity
    API->>U: consent page: choose token lifetime
    U->>API: approve
    API-->>T: authorization code on localhost
    T->>API: exchange code
    API-->>T: personal access token
    T->>T: save in credentials file
```

The token is a normal personal access token that you can delete from your user settings at any time.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terrakube.io/2.34.0/how-it-works/identity-and-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.