Personal access tokens

Personal access tokens (PATs) function like passwords for authenticating with Gitflare’s Git operations over HTTP. Use them to push, pull, and clone repositories without exposing your password.

Overview

Personal access tokens are prefixed with gvx_ and provide a secure way to authenticate Git operations. Unlike password authentication, tokens can be easily revoked without changing your account password.

Use cases

Push and pull Git repositories over HTTPS
Clone private repositories
Authenticate automated workflows and CI/CD pipelines
Provide temporary access without sharing credentials

Token format

Tokens follow this format:

gvx_[random-string]

Example: gvx_abc123def456xyz789

Save your token immediately after creation. You won’t be able to view it again.

Create token

Generate a new personal access token.

curl -X POST https://your-gitflare-instance.com/api/auth/api-key/create \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "My Development Token",
    "prefix": "gvx_"
  }'

Request body

name

string

required

Descriptive name for the token to help you identify it later. Must be between 3 and 50 characters.

prefix

string

default:"gvx_"

Token prefix. Defaults to gvx_ for Gitflare tokens.

expiresAt

timestamp

Optional expiration timestamp in milliseconds. If not provided, the token never expires.

Response

string

Unique token identifier.

key

string

The full token string. This is the only time you’ll see the complete token.

name

string

The descriptive name you provided.

start

string

First few characters of the token (e.g., gvx_abc) for identification.

prefix

string

Token prefix.

enabled

boolean

Whether the token is active.

createdAt

timestamp

Token creation timestamp in milliseconds.

expiresAt

timestamp | null

Token expiration timestamp, or null if it never expires.

Example response

{
  "id": "token_abc123",
  "key": "gvx_abc123def456xyz789",
  "name": "My Development Token",
  "start": "gvx_abc",
  "prefix": "gvx_",
  "enabled": true,
  "createdAt": 1709500000000,
  "expiresAt": null
}

List tokens

Retrieve all personal access tokens for the authenticated user.

curl https://your-gitflare-instance.com/api/auth/api-key/list \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

Response

Returns an array of token objects. Note that the full token key is not included for security reasons.

tokens

array

Array of token objects.

Show token properties

string

Unique token identifier.

name

string

Descriptive token name.

start

string

First few characters of the token (e.g., gvx_abc).

prefix

string

Token prefix.

enabled

boolean

Whether the token is active.

createdAt

timestamp

Token creation timestamp.

lastRequest

timestamp | null

Last time this token was used, or null if never used.

expiresAt

timestamp | null

Token expiration timestamp, or null if it never expires.

requestCount

number

Total number of requests made with this token.

Example response

[
  {
    "id": "token_abc123",
    "name": "My Development Token",
    "start": "gvx_abc",
    "prefix": "gvx_",
    "enabled": true,
    "createdAt": 1709500000000,
    "lastRequest": 1709586400000,
    "expiresAt": null,
    "requestCount": 42
  },
  {
    "id": "token_def456",
    "name": "CI/CD Pipeline",
    "start": "gvx_def",
    "prefix": "gvx_",
    "enabled": true,
    "createdAt": 1709400000000,
    "lastRequest": null,
    "expiresAt": null,
    "requestCount": 0
  }
]

Delete token

Revoke a personal access token. This immediately invalidates the token.

curl -X POST https://your-gitflare-instance.com/api/auth/api-key/delete \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
  -d '{
    "keyId": "token_abc123"
  }'

Request body

keyId

string

required

The ID of the token to delete.

Response

success

boolean

Indicates whether the token was successfully deleted.

Example response

{
  "success": true
}

Using tokens with Git

Once you have a personal access token, use it as your password when performing Git operations over HTTPS.

Clone a repository

git clone https://username:[email protected]/owner/repo.git

Configure credentials

For repeated operations, configure Git to cache your credentials:

# Cache credentials for 1 hour
git config --global credential.helper 'cache --timeout=3600'

# Or store credentials permanently (use with caution)
git config --global credential.helper store

Then perform a Git operation. When prompted:

Username: your-username
Password: gvx_abc123def456

In CI/CD pipelines

Use tokens in automated workflows:

# GitHub Actions example
- name: Clone repository
  run: |
    git clone https://${{ secrets.GITFLARE_USERNAME }}:${{ secrets.GITFLARE_TOKEN }}@your-gitflare-instance.com/owner/repo.git

Token security

Best practices

Use descriptive names

Name tokens based on their purpose (e.g., “CI/CD Pipeline”, “Local Development”) to track usage.

Set expiration dates

For temporary access, set an expiration date when creating the token.

Revoke unused tokens

Regularly review and delete tokens you no longer need.

Use environment variables

Store tokens in environment variables or secret management systems, never in code.

Rotate tokens regularly

Create new tokens and revoke old ones periodically, especially for long-running services.

Limit token scope

Create separate tokens for different purposes instead of sharing a single token.

What to do if a token is compromised

Immediately revoke the compromised token via the delete endpoint
Generate a new token with a different name
Update all services using the old token
Review recent activity to identify any unauthorized access

Token metadata

Gitflare tracks usage information for each token:

Last request: Timestamp of the most recent API call
Request count: Total number of requests made
Created date: When the token was generated

Use this information to:

Identify unused tokens for deletion
Monitor token usage patterns
Detect unusual activity

Rate limiting

Personal access tokens are subject to rate limiting. Rate limiting is currently disabled in Gitflare but can be enabled in the configuration:

apiKey({
  rateLimit: {
    enabled: true,
    max: 100,        // Maximum requests
    window: 3600000, // Time window in ms (1 hour)
  },
})

When rate limiting is enabled:

Each token has its own rate limit
Limits reset after the specified time window
Exceeding limits returns a 429 Too Many Requests error

Error responses

error

object

Error information when a request fails.

Show error properties

message

string

Human-readable error message.

Common error codes

400 Bad Request: Invalid parameters (e.g., name too short)
401 Unauthorized: No active session or invalid session
404 Not Found: Token ID not found
429 Too Many Requests: Rate limit exceeded (when enabled)
500 Internal Server Error: Server-side error

Git Protocol

Repository API

Issues API

Authentication

Personal access tokens

Overview

Use cases

Token format

Create token

Request body

Response

Example response

List tokens

Response

Example response

Delete token

Request body

Response

Example response

Using tokens with Git

Clone a repository

Configure credentials

In CI/CD pipelines

Token security

Best practices

What to do if a token is compromised

Token metadata

Rate limiting

Error responses

Common error codes

See also

Build docs developers (and LLMs) love

Git Protocol

Repository API

Issues API

Authentication

​Overview

​Use cases

​Token format

​Create token

​Request body

​Response

​Example response

​List tokens

​Response

​Example response

​Delete token

​Request body

​Response

​Example response

​Using tokens with Git

​Clone a repository

​Configure credentials

​In CI/CD pipelines

​Token security

​Best practices

​What to do if a token is compromised

​Token metadata

​Rate limiting

​Error responses

​Common error codes

​See also

Build docs developers (and LLMs) love

Overview

Use cases

Token format

Create token

Request body

Response

Example response

List tokens

Response

Example response

Delete token

Request body

Response

Example response

Using tokens with Git

Clone a repository

Configure credentials

In CI/CD pipelines

Token security

Best practices

What to do if a token is compromised

Token metadata

Rate limiting

Error responses

Common error codes

See also