GitFlare API Documentation

Integration Quickstart (Production)

1. Create developer app (dashboard or POST /v1/developer/apps) and store client_id + one-time client_secret.
2. Render hosted Connect URL (/oauth/authorize) in redirect or iframe mode with customer_ref and secure state.
3. Customer approves providers/repositories on hosted consent screen.
4. Receive callback at your redirect_uri with code and verify state.
5. Exchange code via POST /oauth/token and persist accessToken securely.
6. Call unified read endpoints with Authorization: Bearer ACCESS_TOKEN.
7. Implement cursor pagination for collection endpoints using limit + cursor and page_info.next_cursor.
8. Handle canonical errors by error.code and request_id for retries/support workflows.

End-To-End API Flow (At A Glance)

# 1) Create app (developer session)
POST https://api.gitflare.dev/v1/developer/apps
-> persist client.id + clientSecret

# 2) Redirect customer to hosted authorize
GET https://panel.gitflare.dev/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=read:repositories%20read:commits&state=SECURE_STATE&customer_ref=CUSTOMER_EXTERNAL_ID

# 3) Exchange callback code for access token
POST https://api.gitflare.dev/oauth/token
Content-Type: application/json
{
  "grant_type": "authorization_code",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "code": "CODE_FROM_CALLBACK",
  "redirect_uri": "https://yourapp.com/callback"
}

# 4) Read provider data through unified endpoints
GET https://api.gitflare.dev/v1/repositories?provider=github&limit=25
Authorization: Bearer ACCESS_TOKEN

Base URLs And Hosted Routes

Base URL: https://api.gitflare.dev

• Authorize endpoint: https://panel.gitflare.dev/oauth/authorize
• Token endpoint: https://api.gitflare.dev/oauth/token
• Customer management route: https://panel.gitflare.dev/app/company/apps/CLIENT_ID?customer_ref=CUSTOMER_EXTERNAL_ID
• Provider callbacks are platform-managed and exposed via /v1/auth/callback-urls.

Authentication Models

Create App (API Example)

Equivalent to dashboard action, useful for automation in CI/admin tools.

POST https://api.gitflare.dev/v1/developer/apps
Authorization: Bearer DEVELOPER_SESSION_TOKEN
content-type: application/json

{
  "name": "Acme Git Insights",
  "description": "Read-only Git analytics integration",
  "allowedRedirectUris": ["https://acme.example.com/oauth/callback"],
  "defaultPermissions": ["read:profile","read:repositories","read:commits","read:pull-requests","read:tags","read:file-tree"]
}

Authorize URL (Hosted Connect)

https://panel.gitflare.dev/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=read:repositories read:commits&state=SECURE_RANDOM_STATE&customer_ref=CUSTOMER_EXTERNAL_ID

Use one hosted URL per customer. They can connect GitHub/GitLab/Bitbucket accounts, select repositories, and manage future updates in the same hosted flow.

Required query params: response_type=code, client_id, redirect_uri. Strongly recommended: secure random state, stable customer_ref, explicit scope.

<iframe
  src="https://panel.gitflare.dev/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=read:repositories read:commits&state=SECURE_RANDOM_STATE&customer_ref=CUSTOMER_EXTERNAL_ID"
  title="GitFlare Connect"
  style="width:100%;height:760px;border:0;border-radius:16px;"
  loading="lazy"
></iframe>

state Validation (Required)

state protects your OAuth flow against CSRF and callback confusion. Generate a random value per authorization attempt, store it in your backend session/store, and verify the callback state matches exactly.

import crypto from 'node:crypto';

// Before redirecting customer to /oauth/authorize
const state = crypto.randomBytes(24).toString('hex');
session.oauthState = state;

// After callback returns to your redirect_uri
if (!req.query.state || req.query.state !== session.oauthState) {
  throw new Error('Invalid OAuth state');
}

Treat each state value as one-time, short-lived, and bound to the user session that initiated auth.

Token Exchange

POST https://api.gitflare.dev/oauth/token
content-type: application/json

{
  "grant_type": "authorization_code",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "code": "CODE_FROM_CALLBACK",
  "redirect_uri": "https://acme.example.com/oauth/callback"
}

grant_type=authorization_code returns connection-bound tokens for unified read APIs. grant_type=client_credentials is also supported for service-level flows.

{
  "id": "atk_123",
  "accessToken": "sggat_...",
  "tokenType": "Bearer",
  "expiresAt": "2026-04-02T14:00:00.000Z",
  "expiresInSeconds": 3600,
  "tenantId": "tenant_123",
  "clientId": "client_123",
  "authorizationId": "authz_123",
  "issuedBy": "authorization_code",
  "permissions": ["read:repositories","read:commits"],
  "connectionIds": ["conn_1","conn_2"]
}

Supported Read Scopes

Scope catalog can be fetched programmatically from /v1/platform/capabilities.

Pagination Contract (Phase 1)

• Canonical request params: limit and cursor.
• Canonical response fields: items, page_info, meta.
• cursor is opaque. Do not parse or mutate it.
• If no next page: page_info.has_next_page=false and page_info.next_cursor=null.
• Phase 1 repository pagination is provider-scoped: send provider=github|gitlab|bitbucket|azure when using limit/cursor on /v1/repositories.

GET https://api.gitflare.dev/v1/repositories?provider=github&limit=25
Authorization: Bearer ACCESS_TOKEN

GET https://api.gitflare.dev/v1/repositories?provider=github&limit=25&cursor=gf_cur_...
Authorization: Bearer ACCESS_TOKEN

{
  "items": [{ "id": "repo_123", "name": "backend", "fullName": "acme/backend" }],
  "page_info": {
    "next_cursor": "gf_cur_...",
    "has_next_page": true
  },
  "meta": {
    "limit": 25,
    "request_id": "gf_req_123"
  },
  "count": 1,
  "repositories": [{ "id": "repo_123", "name": "backend", "fullName": "acme/backend" }]
}

Deterministic Ordering Assumptions

• /v1/repositories with provider + cursor uses provider-native stable pagination pointer from upstream.
• /v1/repositories/:provider/:repoId/branches uses provider-native branch order; cursor continues from provider next pointer.
• /v1/repositories/:provider/:repoId/commits order is provider-native commit listing, with branch bound into cursor scope.
• /v1/repositories/:provider/:repoId/pull-requests order is provider-native and state is bound into cursor scope.
• /v1/repositories/:provider/:repoId/checks, /deployments, and /file-tree bind filter params into cursor scope.
• Provider support differs by endpoint; unsupported pairs return canonical UNSUPPORTED_ENDPOINT.
• If upstream datasets drift between page calls, GitFlare Phase 1 does not attempt snapshot healing or deduplication.

Canonical Error Model

Every JSON error response follows one shape. Use error.code for deterministic handling.

{
  "error": {
    "code": "INVALID_CURSOR",
    "message": "The provided pagination cursor is invalid.",
    "source": "gitflare",
    "provider": null,
    "retryable": false,
    "user_action_required": true,
    "suggested_action": "restart_pagination",
    "upstream_status": null,
    "request_id": "gf_req_123",
    "provider_request_id": null,
    "retry_after_seconds": null
  }
}

Always log and persist x-request-id response header and error.request_id to speed up support triage.

Query Parameter Reference

Endpoint Cards

Quick scan view of endpoints by method, auth model, scope, and description.

Complete Endpoint Matrix

This table reflects the current server implementation end-to-end, including public, session, OAuth, unified read, internal tooling, and admin routes.

Phase 1 Scope Boundaries

• No previous-page cursor support in Phase 1.
• No cursor history persistence in DB/Redis for Phase 1 cursor handling.
• No cross-provider merged pagination stream in Phase 1.
• No prefetch/caching/smart page filling from multiple upstream pages in a single request.
• No snapshot-consistent pagination guarantees across mutable upstream datasets.

Security Firewall And Data Handling

• Unified third-party data responses are passed through GitFlare security firewall when called with platform access tokens.
• Blocked file path patterns (for example .env, *.pem, *.key) are stripped from diff/file payloads.
• Secret-like assignments (api_key/token/secret/password patterns) are hashed before response leaves GitFlare.
• Firewall config is runtime-managed via /v1/security/firewall/config (admin key required).
• Usage audit logs are recorded for unified read endpoints called with platform access tokens.

Operational Tips

• Use /v1/platform/client/me immediately after token exchange to validate token/client/tenant wiring.
• Store and replay opaque cursors exactly as returned. Never decode or alter cursor strings.
• Treat CURSOR_EXPIRED and INVALID_CURSOR as restart-from-first-page signals.
• For retries on RATE_LIMITED/UPSTREAM_TIMEOUT/UPSTREAM_UNAVAILABLE, apply exponential backoff and idempotent reads.
• Persist request_id for all failed calls for support/debugging correlation.
• If you enable strict mode with ENFORCE_PLATFORM_AUTH=true, legacy x-connection-id fallback is disabled.