Api Key

Secure your API requests with proper authentication. BlockSecOps API uses Bearer token authentication with API keys. Every API request must include a valid API...

Last updated: January 14, 2026

API Authentication

Secure your API requests with proper authentication.

Overview

BlockSecOps API uses Bearer token authentication with API keys. Every API request must include a valid API key in the Authorization header.

API Key Format

API keys follow this format:

bso_<environment>_<random_string>
Prefix Environment Use Case
bso_live_ Production Live API calls
bso_test_ Sandbox Testing and development

Authentication Header

Include your API key in every request:

Authorization: Bearer YOUR_API_KEY

Authentication

All API requests require authentication via Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.blocksecops.com/api/v1/scans

Creating API Keys

Via Dashboard

  1. Go to Settings → API Keys
  2. Click Create New Key
  3. Configure:
    • Name: Descriptive identifier
    • Permissions: Select allowed operations
    • Expiration: Optional expiry date
  4. Click Create
  5. Copy the key (shown only once)

Via API

curl -X POST "https://api.blocksecops.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "permissions": ["scans:read", "scans:write", "contracts:write"],
    "expires_at": "2026-01-01T00:00:00Z"
  }'

Key Permissions

API keys can have granular permissions:

Scope Categories

Scope Description
contracts:read View contracts
contracts:write Upload/delete contracts
scans:read View scan status and results
scans:write Start/cancel scans
vulnerabilities:read View vulnerabilities
vulnerabilities:write Update vulnerability status
organizations:read View organization info
organizations:write Manage organization
webhooks:read View webhooks
webhooks:write Create/delete webhooks
api-keys:read List API keys
api-keys:write Create/revoke API keys

Common Permission Sets

Read-Only Reporting:

["scans:read", "vulnerabilities:read", "contracts:read"]

CI/CD Pipeline:

["contracts:write", "scans:read", "scans:write"]

Full Access:

["*"]

Authentication Errors

401 Unauthorized

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

Causes:

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

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions for this operation"
  }
}

Causes:

  • API key lacks required permission
  • Organization-level restriction
  • Resource belongs to different organization

Security Best Practices

Key Storage

Do:

  • Store keys in environment variables
  • Use secret management services (AWS Secrets Manager, HashiCorp Vault)
  • Encrypt keys at rest

Don't:

  • Commit keys to version control
  • Share keys in plain text
  • Store keys in client-side code
  • Log API keys

Environment Variables

# Set environment variable
export BLOCKSECOPS_API_KEY="bso_live_abc123..."

# Use in scripts
curl -H "Authorization: Bearer $BLOCKSECOPS_API_KEY" ...

CI/CD Secrets

GitHub Actions:

env:
  BLOCKSECOPS_API_KEY: ${{ secrets.BLOCKSECOPS_API_KEY }}

GitLab CI:

variables:
  BLOCKSECOPS_API_KEY: $BLOCKSECOPS_API_KEY

Key Rotation

Regularly rotate API keys for security:

Rotation Process

  1. Create new API key with same permissions
  2. Update applications to use new key
  3. Verify new key works correctly
  4. Revoke old key

Recommended Schedule

Environment Rotation Frequency
Production Every 90 days
CI/CD Every 30 days
Development As needed

IP Allowlisting

Enterprise plans can restrict API key usage to specific IPs:

curl -X PATCH "https://api.blocksecops.com/api/v1/api-keys/{key_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_ips": ["192.168.1.0/24", "10.0.0.1"]
  }'

Organization Context

API keys are scoped to organizations. When you have multiple organizations:

Default Organization

Requests use your default organization unless specified:

# Uses default organization
GET /api/v1/scans

Specify Organization

Use the X-Organization-ID header:

curl -X GET "https://api.blocksecops.com/api/v1/scans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: org_xyz789"

Testing Authentication

Verify your API key works:

curl -X GET "https://api.blocksecops.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response:

{
  "user_id": "user_abc123",
  "email": "[email protected]",
  "organization": {
    "id": "org_xyz789",
    "name": "My Company"
  },
  "permissions": ["scans:read", "scans:write", ...]
}

Troubleshooting

Key Not Working

  1. Check format: Ensure key includes full prefix
  2. Verify not expired: Check key expiration in dashboard
  3. Check permissions: Verify key has required scopes
  4. Confirm organization: Ensure key belongs to correct org

Getting 403 on Valid Key

  1. Check endpoint requires a permission your key has
  2. Verify resource belongs to your organization
  3. Check organization hasn't exceeded plan limits

Next Steps