> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate the Tensorlake CLI, plain Git clients, and versioned file system mounts.

Most users only need one command:

```bash theme={null}
tl login
```

`tl login` opens a browser, authenticates your account, and stores a local CLI token. After that, `tl git` and `tl fs` commands mint the short-lived credentials they need automatically.

You only handle a Git credential yourself when you use plain `git`, CI, or another HTTP client.

## How Authentication Fits Together

There are two layers:

| Layer                   | What it is                                                                                               | Used by                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Tensorlake CLI/API auth | Your account, API key, or personal access token. This authorizes calls to Tensorlake.                    | `tl login`, `tl git`, `tl fs`, API clients         |
| Git credential          | A short-lived credential minted for repository access. This authorizes versioned file system operations. | `git clone`, `git push`, SDK calls, `tl fs` mounts |

Your CLI/API credential is not sent to Git. Tensorlake uses it to mint a Git credential, then Git clients and mounts use that Git credential against the repository service.

## How Git Credentials Work

When a command needs repository access:

1. The CLI authenticates to Tensorlake with your local CLI token, API key, or PAT.
2. Tensorlake checks the current project and authorized principal.
3. Tensorlake mints a short-lived Git credential for that principal.
4. The Git service verifies the credential's signature, project, repo pattern, expiration, revocation status, and scopes on each request.

The credential contains:

| Field         | Meaning                                                         |
| ------------- | --------------------------------------------------------------- |
| `gitUsername` | The Git username. It is always `t`.                             |
| `token`       | The password Git sends with HTTP Basic auth.                    |
| `expiresAt`   | When the credential stops working.                              |
| `repoPattern` | The repository or repository pattern the credential can access. |
| `scopes`      | The operations the credential can perform.                      |

Most CLI paths mint a repo-scoped credential. That keeps clone, push, snapshot, and promotion operations narrow to the repository they are working on.

## Mint a Git Credential

```bash theme={null}
$ tl git token --repo agent-outputs
project: project_9f3c2a1b
repo: agent-outputs
username: t
password: eyJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJwcm9qZWN0XzlmM2MyYTFiIiwicmVwbyI6ImFnZW50LW91dHB1dHMifQ.Kx9f... (truncated)
expires: 2026-07-07T13:00:00Z
scopes: git:read, git:write

Remote URL
  https://git.tensorlake.ai/project_9f3c2a1b/agent-outputs

Use this credential with Git or SDK clients
  username: t
  password: the token above
```

The username is always `t`. The password is the token.

## Use It With Git

<Tabs>
  <Tab title="Credential store">
    Cache the credential with Git's credential helper:

    ```bash theme={null}
    git config --global credential.helper store
    git clone https://git.tensorlake.ai/project_9f3c2a1b/agent-outputs
    Username for 'https://git.tensorlake.ai': t
    Password for 'https://t@git.tensorlake.ai': <paste the token>
    ```

    Git remembers the credential for later commands against the same remote.
  </Tab>

  <Tab title="Embed in URL">
    Put the token directly in the remote URL for scripts and CI:

    ```bash theme={null}
    TOKEN=$(tl git token --repo agent-outputs --json | jq -r .token)

    git clone https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-outputs
    ```

    Or update an existing remote:

    ```bash theme={null}
    git remote set-url origin https://t:$TOKEN@git.tensorlake.ai/project_9f3c2a1b/agent-outputs
    git push origin main
    ```
  </Tab>
</Tabs>

Treat a token in a URL or credential store like any other secret. It expires automatically, but it should not be committed, logged, or shared.

## Scopes

Every credential carries one or more scopes:

| Scope           | Grants                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `git:read`      | Clone, fetch, and read-only mount                                                                                         |
| `git:write`     | Push, snapshot, and promote. Implies `git:read`.                                                                          |
| `repo:write`    | Create, fork, delete, archive, and restore repositories                                                                   |
| `project:read`  | List and read every repository in the project. Implies `git:read`.                                                        |
| `project:admin` | Project administration, workspace fleet management, quotas, and operation history. Implies `project:read` and `git:read`. |

`tl git token --repo <repo>` mints `git:read` and `git:write` for that repository only. It is enough to clone, push, snapshot, and promote. It cannot create, delete, or list other repositories.

Repo-scoped credentials cannot create repositories, delete repositories, manage keys, or revoke tokens.

## Token Lifetime

Git credentials are short-lived by design. The default lifetime is one hour.

When a token expires, mint a new one:

```bash theme={null}
tl git token --repo <repo>
```

`tl fs` handles this automatically. It caches fresh Git credentials for later commands and a running mount daemon rotates its credential before expiry.

For the full plain Git workflow, see [Git Repositories](/filesystems/git-repositories).

<CardGroup cols={2}>
  <Card title="Git Repositories" icon="code-commit" href="/filesystems/git-repositories">
    Mint a credential, clone, branch, commit, merge, and push.
  </Card>

  <Card title="Platform Authentication" icon="key" href="/platform/authentication">
    API keys, personal access tokens, SSO, and broader Tensorlake API authentication.
  </Card>
</CardGroup>