# Tokens

---

## Overview

Give Kubernetes clusters, CI tools, and external systems secure access to your Fly Registry.

If you're using the Fly App locally, you don't need tokens: authentication is handled automatically. Tokens are for systems that can't use the Fly App: Kubernetes clusters pulling images, external CI tools, deployment scripts, or manual package manager configuration.

A token is a credential that provides controlled access to your Fly Registry. Tokens come in two permission levels (read-only or read & write) and can be scoped to a specific runtime environment for deployment tracking.

---

## How It Works

### Token Types

**Read & Write Token** -- Full access to artifacts: upload, download, view metadata, create releases from external CI.

Use cases: manual local development, external CI/CD systems, automated deployment scripts.

**Read-Only Token** -- Limited access: download and view only.

Use cases: Kubernetes environments pulling images, deployment environments, sharing with partners/customers.

### Environment-Scoped Tokens

Tokens can be associated with a specific runtime environment. When scoped to an environment, every image pull using that token is tracked against the environment, enabling Fly to show deployment history and drift detection.

Environment tokens can be generated during environment creation or from the environment profile. See [Runtime Environments →](../runtime-environments/) for details.

### Security Model

- Token values are shown **once** at creation -- copy immediately
- Tokens can be revoked instantly, invalidating all systems using them
- Revoked tokens cannot be unrevoked
- The system tracks token creation, usage, and status
- Admins can revoke any token; Developers can only revoke their own

---

## From Your Coding Agent

Your coding agent can generate tokens and configure package managers for you. This is especially useful when setting up new environments or connecting external systems.

### Generate Tokens

*"Generate a deployment token for production"*

*"Create a read-only token for staging"*

Fly generates the token, optionally associates it with an environment, and provides the credentials.

### Use Tokens for Package Managers

Tokens can manually configure package managers in environments without the Fly App:

**Docker:**
```bash
docker login <your-fly-subdomain>.jfrog.io -u <your-fly-username> -p <your-fly-token>
```

**npm** (add to `.npmrc`):
```
registry=https://<your-fly-subdomain>.jfrog.io/artifactory/api/npm/npm/
//<your-fly-subdomain>.jfrog.io/artifactory/api/npm/npm/:_authToken=<your-fly-token>
```

**pip:**
```bash
export PIP_INDEX_URL=https://<your-fly-username>:<your-fly-token>@<your-fly-subdomain>.jfrog.io/artifactory/api/pypi/pypi/simple
```

See [Package Managers →](../../package-managers/) for all package types.

---

## In Fly Web

Fly Web provides a token management dashboard where you can create, view, and revoke tokens. Access it from your user avatar in the top-right corner.

### Creating Tokens

1. Click your **user avatar** (top-right) → **Token Management**
2. Click **Create Token**
3. Configure: **Name**, **Permission** (Read & Write or Read-Only), **Expiration** (date or "Never")
4. Click **Create**
5. **Copy token immediately** -- shown only once

### Viewing Tokens

| Column | Description |
|--------|-------------|
| **Name** | Token name |
| **Username** | Token-specific username for authentication |
| **Permission** | Read & Write or Read-Only |
| **Created By** | User who created the token |
| **Created** | Creation timestamp |
| **Expires** | Expiration date |
| **Status** | Active, Expired, or Revoked |

### Revoking and Deleting Tokens

- **Revoke** -- Immediately invalidates the token. Any systems using it lose access. Admins can revoke any token; Developers can only revoke their own.
- **Delete** -- Removes expired or revoked tokens from the list. Cannot delete active tokens.

---

## Next Steps

- [Runtime Environments →](../runtime-environments/) - Environment-scoped tokens and pull secrets
- [Package Managers →](../../package-managers/) - Manual package manager configuration with tokens