# Accounts, passwords, API keys, permissions

> **What you will learn**
> Authentication versus authorisation, what passwords, tokens and keys each are,
> why least privilege is the rule, and what to do when a key leaks.

## There are two questions

```mermaid
graph TD
  A["a request arrives"] --> B["authentication<br/>who is this?"]
  B -->|"unknown → 401"| X["refused"]
  B -->|"identified"| C["authorisation<br/>may they do this?"]
  C -->|"no → 403"| X
  C -->|"yes"| D["run it"]
```

| | Authentication | Authorisation |
|---|---|---|
| Asks | **who are you** | **what may you do** |
| Means | password · key · SSO | roles · permissions |
| On failure | `401` | `403` |

**The 401 and 403 from [HTTP](/guide/it-http) are exactly these two.** No number
of fresh keys resolves a 403 — that needs a permission.

## Three ways to prove identity

| | Password | Token · API key | SSO |
|---|---|---|---|
| Used by | a person | **a program** | a person |
| How many | one | one per purpose | one company account |
| Expiry | none until changed | **can be time-limited** | per session |
| If leaked | the whole account | **only that key's scope** | cut off by company policy |

**The bottom two rows are why tokens beat passwords here.** Scope and lifetime
can be narrowed, so a leak stays inside that scope. The `tt_`-prefixed system
tokens in HyperTeams and Connect's API keys both work this way
([Calling it via API key](/guide/cn-api)).

## Least privilege — only what is needed now

```
✗ Grant admin now and narrow it later   → "later" never arrives
✓ Grant what is needed; widen when something is blocked
```

Widening happens the moment someone is blocked. **Narrowing only gets noticed
after someone's work stops.** Order matters — [Tools are
permissions](/guide/mcp-security) and [Members and roles](/guide/cn-members)
apply the same rule to tools and to people.

**It applies to agents identically.** An agent acts with **the permissions of the
account it was given**, not its own. Give it a read-only account and it cannot
delete anything even if asked.

## Two-factor — something you know plus something you have

A password is **something you know**, so learning it is enough to be you. Adding
**something you have** (an authenticator on a phone) is two-factor
authentication (2FA/MFA).

> **Turn it on for administrator accounts without exception.** Most incidents
> start not with sophisticated attacks but with a password leaked elsewhere
> being tried here.

## Passwords fail through reuse

```
□ A different password per service — one breach stays one breach
□ Length beats complexity — a long phrase outperforms a short cryptic string
□ Use a password manager — reuse comes from trying to memorise
```

## Keys are harder to retire than to issue

Creating a key takes ten seconds; finding everywhere it was planted takes days.

```
□ Give it a recognisable name    ✓ "intranet-summariser"   ✗ "key1" · "test"
□ Record where you put it
□ Never paste it into code or a chat window
□ Rotate it when the owner changes
□ If it leaks, delete and re-issue — you retire it, you do not repair it
```

**Do not leave keys in a `.env` and push it to a shared folder or repository.**
That is why the hidden files from [Files, folders, paths](/guide/it-files) are
dangerous — invisible, and uploaded along with everything else.

## Permissions attach to roles, not people

| | Per-person settings | **Roles** |
|---|---|---|
| New joiner | configure each thing | assign a role |
| Leaver | hunt down where they had access | revoke the role |
| Audit | one per person | one per role |

That is the job of [Members and roles](/guide/cn-members) and
[Groups and departments](/guide/cn-groups), and joining it to the company
directory is [SSO](/guide/cn-sso).

## Common misconceptions

### "We are small — do we really need permission tiers?"

**It is about incidents, not people.** If one account leaks, everything it can
reach leaks, and an accidental deletion reaches exactly as far.

### "Keeping the key in the code is convenient"

It is. And the moment that code is copied or shared, the key travels with it.
**Keys in configuration, only names in code.**

---

## Check yourself

**1. Authentication versus authorisation?**

<details>
<summary>Answer</summary>

**Authentication asks "who are you"; authorisation asks "what may you do".** They
surface as 401 and 403.
</details>

**2. Why is "grant broadly now, narrow later" dangerous?**

<details>
<summary>Answer</summary>

**Narrowing gets postponed.** Being blocked is reported immediately; excessive
permission is noticed only after an incident.
</details>

**3. What do you do when an API key leaks?**

<details>
<summary>Answer</summary>

**Retire it and issue a new one.** You do not repair it — which is why each key
needs a name telling you where it was used.
</details>

---

That is **IT basics.** Now look at AI itself with the same eyes →
[What a language model actually does](/guide/ai-language-model)