Authentication

The BioQuery API uses API keys for authentication. This guide covers how to obtain, use, and manage your keys.

Getting an API Key

Generate a Key

1. Sign in to bioquery.io 
2. Click your profile icon → Settings
3. Navigate to API Keys
4. Click Generate New Key
5. Give your key a descriptive name (e.g., “Lab Analysis Script”)
6. Copy the key immediately (it won’t be shown again)

Key Format

API keys are prefixed with bq_ followed by a random string:

bq_sk_a1b2c3d4e5f6g7h8i9j0...

Using Your API Key

HTTP Header (Recommended)

Include your API key in the Authorization header:

curl -X POST https://api.bioquery.io/v1/query \
  -H "Authorization: Bearer bq_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "Is DDR1 higher in KIRP vs KIRC?"}'

Query Parameter (Not Recommended)

You can also pass the key as a query parameter, but this is less secure:

curl "https://api.bioquery.io/v1/query?api_key=bq_sk_your_key_here"

Security Best Practices

Do

• ✅ Store keys in environment variables
• ✅ Use different keys for different applications
• ✅ Rotate keys periodically
• ✅ Revoke unused keys immediately

Don’t

• ❌ Commit keys to version control
• ❌ Share keys in plain text (Slack, email)
• ❌ Use the same key for all applications
• ❌ Embed keys in client-side code

Environment Variables

Store your key in an environment variable:

export BIOQUERY_API_KEY="bq_sk_your_key_here"

Then reference it in your code:

Python:

import os
from bioquery import BioQuery
 
client = BioQuery(api_key=os.environ["BIOQUERY_API_KEY"])

Node.js:

const BioQuery = require('bioquery');
 
const client = new BioQuery({
  apiKey: process.env.BIOQUERY_API_KEY
});

Managing Keys

View Active Keys

1. Go to Settings → API Keys
2. See all active keys with:
   • Name
   • Partial key (last 4 characters)
   • Created date
   • Last used date

Revoke a Key

1. Go to Settings → API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm revocation

Rotate Keys

To rotate a key:

1. Generate a new key
2. Update your application to use the new key
3. Test that everything works
4. Revoke the old key

Troubleshooting

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Causes:

• Missing Authorization header
• Invalid key format
• Revoked key
• Expired key

Solutions:

• Check that you’re using the full key
• Verify the key is active in Settings
• Generate a new key if needed

403 Forbidden

{
  "error": "forbidden",
  "message": "API access not enabled for this account"
}

Cause: Your account doesn’t have API access.

Solution: Contact us to request Researcher access.