View as Markdown

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:

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

# 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):

# 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:

# 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.