Authentication

Every API request must include your API key in the Authorization header as a Bearer token.

curl https://api.firsthandapi.com/v1/jobs \
  -H "Authorization: Bearer fh_live_sk_abc123..."

API Key Types

FirstHandAPI uses two types of API keys, distinguished by prefix:

Switch between environments by changing your API key — no code changes needed.

Getting Your API Key

1. Sign up at dashboard.firsthandapi.com
2. Navigate to API Keys in the sidebar
3. Click Create Key and select your scopes
4. Copy the key immediately — it’s only shown once

Or programmatically:

curl -X POST https://api.firsthandapi.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "My Organization", "email": "dev@example.com"}'

Response:

{
  "organization_id": "org_01HV...",
  "api_key": "fh_live_sk_abc123...",
  "credits_cents": 500
}

Every new account receives $2.50 in free credits.

Scopes

API keys have granular scopes that control what they can access:

Dashboard session keys include all scopes. Keys created via the API can be scoped to specific permissions.

Key Rotation

To rotate a key without downtime:

1. Create a new key with the same scopes
2. Update your application to use the new key
3. Verify the new key works
4. Revoke the old key via DELETE /v1/api_keys/:id

Security Best Practices

• Never expose API keys in client-side code — keep them server-side only
• Use environment variables — don’t hardcode keys in source code
• Use minimum necessary scopes — a key that only reads jobs doesn’t need billing:write
• Rotate keys regularly — especially after team member departures
• Use sandbox keys for testing — never test with production keys

SDK Authentication

// TypeScript
import { FirstHandClient } from '@firsthandapi/sdk';
const client = new FirstHandClient({ apiKey: process.env.FIRSTHAND_API_KEY });

# Python
from firsthandapi import FirstHandClient
client = FirstHandClient(api_key=os.environ["FIRSTHAND_API_KEY"])

Error Responses

If authentication fails, the API returns:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing API key",
    "request_id": "req_01HV..."
  }
}