---
title: "Authentication"
description: "Create and manage Personal Access Tokens for the Forkline API."
section: "reference"
url: "https://forkline.dev/docs/reference/authentication"
markdown: "https://forkline.dev/docs/reference/authentication.md"
source: "src/content/docs/reference/authentication.mdx"
---

# Authentication

The Forkline API uses Personal Access Tokens (PATs) for authentication. Tokens are scoped and revocable.

## Creating a Token

1. Log in to the Forkline web application
2. Navigate to **Settings** -> **API Tokens**
3. Click **Create Token**
4. Enter a descriptive name (e.g., "CI Pipeline", "Local Development")
5. Select the scopes your integration needs
6. Choose an expiration option: set a duration (default 90 days, maximum 365 days) or select **Never expires**
7. Click **Create**

> **Warning**: The full token is shown **exactly once** at creation. Copy it immediately and store it securely. You cannot retrieve it later.

## Using a Token

Include the token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer fl_pat_v1_abc123_xyz789" \
  https://api.forkline.dev/v1/me
```

## Scopes

Each token is granted a specific set of scopes that limit which API endpoints it can access:

| Scope | Description |
|-------|-------------|
| `user:read` | Read your profile information |
| `user:write` | Update your profile settings |
| `repositories:read` | List and read repositories |
| `repositories:write` | Create, update, and delete repositories |
| `runners:read` | List and read runners and their events |
| `runners:write` | Start, stop, and manage runners |
| `runners:attach` | Obtain short-lived attach grants for running runners |
| `models:read` | List available models and providers |
| `analytics:read` | Access analytics and usage data |
| `routines:read` | List and read routines |
| `routines:write` | Create, update, and delete routines |
| `routines:execute` | Run routines now |
| `connectors:read` | List git connectors |
| `billing:read` | Read billing and credit information |
| `tokens:manage` | Create, list, and revoke API tokens |
| `secrets:manage` | Manage repository and account secrets |
| `providers:manage` | Import and manage custom AI providers |
| `mcp:read` | Browse the MCP catalog and read your MCP servers |
| `mcp:write` | Create, update, upgrade, and delete MCP servers |

> **Note**: The `routines:write` scope allows you to modify routines but does not allow executing them. Use `routines:execute` to run routines now (`POST /v1/routines/{id}/run`).

## Token Expiry and Revocation

Tokens expire either on the date you set during creation or when manually revoked. Expired tokens return `401 Unauthorized`.

To revoke a token before it expires:

1. Go to **Settings** -> **API Tokens**
2. Find the token you want to revoke
3. Click **Revoke**

Revoked tokens are immediately invalidated and cannot be used for further requests.

## Managing Tokens

Token management (creation, listing, revocation) is available through the web application, the app-domain API, or the public API using a PAT with the `tokens:manage` scope.

> **Security note**: A PAT with `tokens:manage` can create new tokens with any combination of scopes, including scopes broader than the managing token itself. Rotate and protect `tokens:manage` tokens with extra care.

### Public API

```bash
# List your tokens
curl -H "Authorization: Bearer $FORKLINE_TOKEN" \
  https://api.forkline.dev/v1/me/api-tokens

# Create a token
curl -X POST \
  -H "Authorization: Bearer $FORKLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI", "scopes": ["runners:read"], "expires_in_days": 90}' \
  https://api.forkline.dev/v1/me/api-tokens

# Revoke a token
curl -X DELETE \
  -H "Authorization: Bearer $FORKLINE_TOKEN" \
  https://api.forkline.dev/v1/me/api-tokens/{token_id}
```

### App-Domain API

You can also manage tokens via the main application API (requires browser session):

```bash
# List your tokens
curl -H "Cookie: session=..." https://app.forkline.dev/api/v1/me/api-tokens

# Create a token
curl -X POST -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{"name": "CI", "scopes": ["runners:read"], "expires_in_days": 90}' \
  https://app.forkline.dev/api/v1/me/api-tokens

# Revoke a token
curl -X DELETE -H "Cookie: session=..." \
  https://app.forkline.dev/api/v1/me/api-tokens/{token_id}
```

## Security Best Practices

### Never Commit Tokens

Do not commit tokens to version control. Use environment variables or secret management tools:

```bash
# Good: Use environment variable
curl -H "Authorization: Bearer $FORKLINE_TOKEN" https://api.forkline.dev/v1/me

# Bad: Hardcoded token
curl -H "Authorization: Bearer fl_pat_v1_abc123..." https://api.forkline.dev/v1/me
```

### Use Least Privilege

Grant only the scopes your integration needs. A CI pipeline that only reads runner status does not need `repositories:write`.

### Rotate Regularly

Create new tokens periodically and revoke old ones. For tokens that expire, set durations to enforce rotation. For tokens with **Never expires**, rotate them manually on a regular schedule.

### Monitor Usage

Check the **Last Used** timestamp in the API Tokens settings to detect unused or suspicious tokens. Revoke any token you do not recognize.

### Store Securely

Use secret management tools (Vault, AWS Secrets Manager, GitHub Secrets) to store tokens. Never log them or expose them in client-side code.

## Token Limits

- **Maximum 50 active tokens per user**
- **Maximum expiration**: 365 days (or **Never expires**)
- **Default expiration**: 90 days; **Never expires** is available as an option

## Troubleshooting

### 401 Unauthorized

Your token is missing, expired, or revoked. Check:

- The `Authorization` header is present and correctly formatted
- The token has not expired (check the expiration date in Settings)
- The token has not been revoked

### 403 Forbidden

Your token does not have the required scope for this endpoint. Check the endpoint documentation for the required scope and update your token.