Skip to main content

​
Overview

BlockDB uses OAuth 2.0 with JWT bearer tokens for API authentication. All requests must include a valid token in the Authorization header. Tokens are scoped to specific datasets, chains, and rate limits.

​
Authentication Flow

1

Request Access

Contact [email protected] to request API access. Provide:
  • Your organization name
  • Intended use case
  • Required datasets and chains
  • Expected request volume
2

Receive Credentials

You’ll receive:
  • Client ID and Client Secret for token generation
  • Scopes defining your access permissions
  • Rate limits based on your plan
3

Generate JWT Token

Use your credentials to request a JWT token from the UserService authentication endpoint.
4

Include in Requests

Send the token in the Authorization header with every API request:
Authorization: Bearer <your_jwt_token>

​
Token Format

All tokens must be sent as Bearer tokens in the HTTP Authorization header:

​
Token Scopes

Tokens are scoped to specific resources. Common scopes include:
Scope PatternDescriptionExample
level:01Access to datasets level 1 (raw data)level:01
level:*Access to all datasets levelslevel:*
chain:1Access to Ethereum Mainnetchain:1
chain:*Access to all chainschain:*
Scopes are comma-separated when requesting tokens. Your token will only grant access to resources explicitly included in your scopes.

​
Token Expiration

  • Access tokens: Configurable by the user. Default behavior is no automatic expiration, but you can define a custom TTL (time-to-live) per application or API key.
  • Refresh tokens: Configurable lifetime as well. Default behavior is no automatic expiration, but you can define a custom TTL (time-to-live) per application or API key.
  • Token rotation: Recommended every 24 hours for security practices.
Expired tokens return 401 Unauthorized. Implement automatic token refresh in your client to avoid interruptions.

​
Error Responses

​
401 Unauthorized

Returned when:
  • Token is missing
  • Token is invalid or expired
  • Token lacks required scopes

​
403 Forbidden

Returned when:
  • Token is valid but lacks required permissions
  • Requested dataset is not included in token scopes
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "Token does not include scope: dataset:0101"
  }
}

​
Best Practices

Store tokens securely and never commit them to version control. Use environment variables or secure secret management systems.
Implement exponential backoff when receiving 401 errors. Refresh your token and retry the request.
For production applications, use a token refresh mechanism that automatically renews tokens before expiration.

​
Testing Authentication

Verify your token is working correctly: 
curl -X POST 'https://api.blockdb.io/v1/evm/blocks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "chain_id": 1,
    "block_numbers": [12345678]
  }'
A successful response confirms your token is valid and has the required scopes.

​
See Also

curl -X POST 'https://api.blockdb.io/v1/evm/blocks' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999
  }'

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": "Token expired at 2025-01-15T10:30:00Z"
  }
}