Authentication

Learn how to authenticate your API requests using organization-scoped API keys with service-level access control.

Overview

The Bounty Lab API uses Bearer token authentication. Your API key serves as your authentication credential for all API requests.

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Authentication Architecture

How It Works

1. You authenticate with your Bounty Lab API key - Not a personal token
2. Bounty Lab handles source authentication - We use our own tokens internally
3. Service access is controlled per API key - Each key has specific service permissions

This architecture means you never need to manage tokens yourself. Bounty Lab handles all API interactions on your behalf.

GraphQL Proxy

When using the GraphQL proxy (/api/github/graphql):

• You provide: Your Bounty Lab API key via Bearer token
• Bounty Lab provides: Authentication using our managed token pool
• You can query: Any GraphQL query (read-only)
• You cannot: Execute mutations - only queries are supported

This proxy abstracts away rate limiting and token management while giving you full access to the GraphQL API.

Creating API Keys

API keys are created and managed through the Bounty Lab dashboard on a per-organization basis.

Step-by-Step Guide

1. Log in to the Bounty Lab dashboard
2. Select your organization from the dropdown
3. Navigate to Settings > API Keys
4. Click Create API Key
5. Enter a descriptive name (e.g., “Production”, “Staging”, “CI/CD”)
6. Click Create

Important: Save Your Key

Your API key is displayed only once during creation. Copy it immediately and store it securely. You will not be able to view it again.

# Store in environment variables
BOUNTYLAB_API_KEY=bl_live_1234567890abcdef

Understanding Services

Bounty Lab provides access to three distinct services. These services are enabled at the organization level by the Bounty Lab team:

Available Services

Service	Description	Endpoints
RAW	Access to raw user and repository data	/api/raw/*
SEARCH	Access to semantic search endpoints	/api/search/*
GITHUB_GRAPHQL	Access to GraphQL proxy	/api/github/*

How Service Access Works

1. Organization-Level Enablement: Services are enabled for your organization by the Bounty Lab team based on your plan or specific request
2. Key Creation Snapshot: When you create an API key, it snapshots the services currently enabled for your organization
3. Static Permissions: The API key retains those service permissions until it is revoked

When New Services Are Enabled

When the Bounty Lab team enables a new service for your organization, existing API keys will not have access to it. You must:

1. Create a new API key in the dashboard
2. Update your applications to use the new key
3. Revoke the old key once migration is complete

This design ensures explicit control over which services each key can access.

Using API Keys

Basic Authentication

Include your API key in the Authorization header using the Bearer token format:

curl "https://api.bountylab.io/api/raw/users/by-login" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"logins": ["octocat"]}'

Using SDKs

The official SDKs handle authentication automatically. See the API Reference and Swagger documentation for endpoint details and examples.

Security Best Practices

1. Use Environment Variables

Never hardcode API keys in your source code. Always use environment variables:

// Good - Environment variables
const apiKey = process.env.BOUNTYLAB_API_KEY;

// Bad - Hardcoded
const apiKey = "bl_live_1234567890abcdef";

2. Secure Storage

Store API keys securely based on your environment:

• Production: Use secret management services (AWS Secrets Manager, HashiCorp Vault, Google Secret Manager)
• Development: Use .env files and add them to .gitignore
• CI/CD: Use encrypted environment variables or secrets management features

# .env file (add to .gitignore!)
BOUNTYLAB_API_KEY=bl_live_1234567890abcdef

3. Separate Keys per Environment

Create dedicated API keys for each environment to limit blast radius:

• Development
• Staging
• Production
• CI/CD pipelines

This isolation makes it easier to rotate keys and trace usage patterns.

4. Rotate Keys Regularly

Rotate your API keys periodically, especially when:

• An employee with key access leaves the team
• You suspect a key may have been compromised
• As part of regular security maintenance (every 90 days recommended)
• The Bounty Lab team enables new services for your organization

5. Monitor Usage

Regularly review your API keys in the dashboard:

• Check when each key was last used
• Monitor for unexpected usage patterns
• Revoke unused or unnecessary keys immediately

6. Never Log API Keys

Ensure your application does not log API keys:

// Good - Log context without sensitive data
logger.info("API request started", { endpoint: "/api/raw/users" });

// Bad - Logs the API key
logger.info("API request", { apiKey, endpoint: "/api/raw/users" });

7. Use HTTPS Only

Always use HTTPS for API requests to prevent interception. The Bounty Lab API enforces HTTPS for all endpoints.

Common Authentication Errors

401 Unauthorized - Missing API Key

{
  "error": "API key is required. Provide via Authorization header (Bearer <token>)."
}

Cause: No API key was provided in the request.

Solution: Include your API key in the Authorization header with the Bearer prefix:

Authorization: Bearer YOUR_API_KEY

403 Forbidden - Invalid API Key

{
  "error": "Invalid API key"
}

Cause: The API key is malformed, expired, or revoked.

Solution:

1. Verify the API key is correct (check for extra spaces or characters)
2. Confirm the key has not been revoked in the dashboard
3. Create a new API key if needed

403 Forbidden - Service Access Denied

{
  "error": "Access denied. This API key does not have access to the SEARCH service.",
  "requiredService": "SEARCH"
}

Cause: Your API key does not have permission to access the requested service.

Solution:

1. Service not enabled: Contact the Bounty Lab team to enable the service for your organization
2. Old API key: If the service was recently enabled, create a new API key to snapshot the updated permissions

403 Forbidden - Organization Membership

{
  "error": "User is not a member of the organization associated with this API key"
}

Cause: The user who created the API key is no longer a member of the organization.

Solution: Have a current organization member create a new API key, then revoke the old one.

Managing API Keys

Viewing Keys

In Settings > API Keys, you can view:

• All active API keys for your organization
• When each key was created
• The last time each key was used
• Which services each key has access to

Note: The actual key value is only shown once at creation time. Store it securely.

Revoking Keys

To revoke an API key:

1. Navigate to Settings > API Keys
2. Find the key you want to revoke
3. Click Revoke or Delete
4. Confirm the action

Once revoked, the key stops working immediately. Any requests using the revoked key will receive a 403 Forbidden error.

Naming Conventions

Use descriptive names that indicate the key’s purpose and environment:

• Production - Main Application
• Staging - Integration Tests
• CI/CD - Actions
• Development - Local Testing

Good naming makes it easier to audit usage and rotate keys systematically.

Key Takeaways

1. Bearer token authentication - Include your Bounty Lab API key in the Authorization header
2. Bounty Lab handles source tokens - You never need to manage authentication yourself
3. Service-level access control - API keys have specific service permissions set at creation time
4. Read-only GraphQL - Mutations are not supported, only queries
5. Organization-scoped - All API keys are tied to a specific organization
6. Create new keys for new services - Existing keys do not automatically gain access to newly enabled services

Next Steps

• Review the API Reference for detailed endpoint specifications
• Explore the Swagger documentation for interactive testing