Authentication

Every GhostFlow API request requires two things:

1. Authentication — an API key (gf_...) in the Authorization header
2. Team context — your Team ID in the X-Team-Id header

curl https://devcore.getghostflow.io/api/v1/campaigns \
  -H "Authorization: Bearer gf_your_api_key_here" \
  -H "X-Team-Id: your-team-uuid-here"

Caution

If you omit the X-Team-Id header, the API will return a 401 error with MISSING_TEAM_CONTEXT. This is the most common mistake when using the API for the first time.

Why X-Team-Id?

GhostFlow is a multi-tenant platform — one user can belong to multiple teams (organizations). The X-Team-Id header tells the API which team’s data to access. The dashboard handles this automatically when you switch teams in the sidebar (team selector), but when calling the API directly you must include it.

API Keys

GhostFlow uses API keys prefixed with gf_ for programmatic access. Keys are passed via the Authorization header using the Bearer scheme:

Authorization: Bearer gf_abc123def456...

Creating API Keys

Generate keys from the Settings → API Keys page in your dashboard, or programmatically:

curl -X POST https://devcore.getghostflow.io/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Team-Id: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "permissions": ["read:campaigns", "write:campaigns", "read:stats"]
  }'

Caution

The full API key is only shown once at creation time. Store it securely — you cannot retrieve it later.

Finding Your Team ID

1. Log in to the GhostFlow Dashboard

2. Open your browser DevTools (F12 or Ctrl+Shift+I)

3. Go to the Network tab

4. Perform any action (e.g., reload the page)

5. Click any request to the API and look for the x-team-id header in Request Headers — that UUID is your Team ID

Tip

You can also call GET /api/v1/auth/me with just your JWT token — the response includes your team_id.

Permissions (Scopes)

Each API key can be scoped to specific permissions. Scopes follow the action:resource pattern:

Scope	Description
read:campaigns	List and view campaigns
write:campaigns	Create, update, delete campaigns
read:domains	List and view domains
write:domains	Create, update, delete domains
read:offers	List and view offers
write:offers	Create, update, delete offers
read:sources	List and view traffic sources
write:sources	Create, update, delete sources
read:networks	List and view affiliate networks
write:networks	Create, update, delete networks
read:stats	Access statistics and reports
read:billing	View subscription and billing info
admin	Full administrative access

Legacy permissions (read, write, admin) are still supported and automatically expanded:

• read → all read:* scopes
• write → all read:* + write:* scopes
• admin → all scopes

Key Management

Action	Endpoint	Method
List keys	/api/v1/auth/api-keys	GET
Create key	/api/v1/auth/api-keys	POST
Delete key	/api/v1/auth/api-keys/{id}	DELETE
Revoke key	/api/v1/auth/api-keys/{id}/revoke	PUT
Regenerate key	/api/v1/auth/api-keys/{id}/regenerate	POST
Audit log	/api/v1/auth/api-keys/{id}/audit-log	GET

Security Best Practices

1. Use least-privilege scopes — Only grant the permissions each integration needs
2. Rotate keys regularly — Use the regenerate endpoint to get a new secret
3. Never commit keys — Use environment variables or secret managers
4. Monitor usage — Check the audit log for unexpected API activity
5. Revoke compromised keys immediately — Revoking is instant and cannot be undone

JWT Tokens

For browser-based access (dashboard), GhostFlow uses short-lived JWT access tokens with refresh token rotation. API keys are preferred for server-to-server integrations.