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

# Core Concepts

> Learn how Code Storage works under the hood. Understand repository IDs, JWT-based authentication, permission scopes, and how customer-signed tokens give you complete control over access.

### Repository management

Code Storage repositories are identified by unique IDs. You can either let the system generate an ID
or provide your own:

```js theme={"theme":{"light":"github-light","dark":"min-dark"}}
// Auto-generated ID
const repo = await store.createRepo();
console.log(repo.id); // e.g., '123e4567-e89b-12d3-a456-426614174000'

// Custom ID with namespacing
const customRepo = await store.createRepo({ id: 'team/project-alpha' });
console.log(customRepo.id); // 'team/project-alpha'
```

Repository IDs can include `/` for organizing repositories by team, project, or user.

### Authentication & Security

All access to Code Storage requires JWT tokens signed by your organization. Each token:

* Grants access to a **single repository** (except `org:read` tokens, which are org-wide)
* Contains **explicit permission scopes**
* Has a **configurable time-to-live (TTL)**
* Is **customer-signed** for full control

The SDK helps simplify and automate the management of these tokens.

### Token structure

```json theme={"theme":{"light":"github-light","dark":"min-dark"}}
{
  "iss": "your-org", // Your organization identifier
  "sub": "ci-pipeline-prod", // Agent identity (for logging)
  "repo": "team/project-alpha", // Repository access
  "scopes": ["git:read", "git:write"], // Permissions
  "iat": 1723453189, // Issued at (Unix timestamp)
  "exp": 1723456789 // Expiration (Unix timestamp)
}
```

JWT headers must include:

```json theme={"theme":{"light":"github-light","dark":"min-dark"}}
{
  "alg": "ES256", // Algorithm (ES256 or RS256 are supported)
  "typ": "JWT", // Type
}
```

### Permission scopes

| Scope        | Description              | Operations                                                 |
| ------------ | ------------------------ | ---------------------------------------------------------- |
| `git:read`   | Read repository contents | clone, fetch, pull                                         |
| `git:write`  | Modify repository        | push (includes read)                                       |
| `repo:write` | Create repositories      | [POST /api/repos](/reference/api/repositories/create-repo) |
| `org:read`   | List repositories        | [GET /api/repos](/reference/api/repositories/list-repos)   |

### Key management

Public keys for JWT verification are managed through the Pierre Admin Panel.

For detailed authentication setup, manual JWT generation, and advanced token configuration, see [Authentication](/getting-started/authentication).