> For the complete documentation index, see [llms.txt](https://docs.kira.thiennguyen.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kira.thiennguyen.dev/getting-started/sso-login.md).

# SSO & First Login

Kira authenticates to AWS through **IAM Identity Center (AWS SSO)**. You sign in once in the browser, and Kira uses the resulting short-lived credentials to assume roles across your accounts.

## Connect your SSO portal

On first run, point Kira at your organization's SSO portal:

* **SSO start URL** — e.g. `https://my-org.awsapps.com/start`
* **SSO region** — the region your Identity Center instance runs in (e.g. `us-east-1`)

These are stored as `ssoStartUrl` and `ssoRegion` in your [configuration](/getting-started/configuration.md).

## The login flow

```mermaid
sequenceDiagram
    participant U as You
    participant K as Kira
    participant B as Browser
    participant S as AWS IAM Identity Center

    U->>K: Click "Login"
    K->>B: Open SSO authorize URL
    B->>S: Sign in / approve device
    S-->>B: Authorization granted
    B-->>K: Token returned
    K->>S: List accounts & roles you can access
    S-->>K: Accounts + roles
    K-->>U: Account picker ready
```

Once authenticated, Kira lists the accounts and roles your SSO permission sets grant. You pick an account and role to start working; Kira remembers your last choice. The SSO session is refreshed automatically until it expires, at which point you log in again.

## Accounts: discovered vs. curated

* **Discovered** — every account/role your SSO login can see is available from the account picker, with no configuration required.
* **Curated** — you can also pin a focused set of accounts in your [configuration](/getting-started/configuration.md) under `accounts`, each with a default `region` and optional pre-listed `secrets` and `ecsClusters`. This is handy when you only care about a handful of accounts or want quick links to specific resources.

## Environment tagging

To tell production apart from staging at a glance, Kira can tag each account with an environment label. Define `envRules` in your [configuration](/getting-started/configuration.md) — each rule matches an account by name or email with a regular expression and assigns an `env` label (e.g. `prd`, `stg`, `dev`). Accounts can also carry an explicit `env` value.

## Next step

With login working, learn how to move around the app in [Navigating Kira](/user-guide/navigation.md), or fine-tune behaviour in [Configuration](/getting-started/configuration.md).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kira.thiennguyen.dev/getting-started/sso-login.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.