Authentication API

rrelayer supports multiple authentication methods:

Basic Authentication

Use HTTP Basic Authentication with username and password:

# curl automatically encodes credentials with -u flag
curl https://your-rrelayer.com/relayers \
  -u "username:password"

Basic authenticated requests must include proper authentication headers:

Authorization: Basic <base64-encoded-credentials>

Basic authentication is configured in your rrelayer.yaml:

api_config:
  port: 3000
  authentication_username: '${RRELAYER_AUTH_USERNAME}'
  authentication_password: '${RRELAYER_AUTH_PASSWORD}'

you can read more about that here

API Key Authentication

Use API keys in the x-rrelayer-api-key header:

curl https://your-rrelayer.com/relayers \
  -H "x-rrelayer-api-key: your-api-key"

API key authentication is configured in your rrelayer.yaml:

rrelayer.yaml

...
networks: 
  - name: local_anvil
    chain_id: 31337
    provider_urls:
      - http://127.0.0.1:8545
    block_explorer_url: http://localhost:8545
    api_keys: 
    - relayer: "0x6f3e343161c4b905342015ad20a5c492adfb730e"
      keys: 
       - "${API_KEY_1}"
       - "${API_KEY_2}"
    - relayer: "0x70e0ba845a1a0f2da3359c97e0285013525ffc49"
      keys: 
       - "${API_KEY_3}"

you can read how to set APIs keys in here

Status Check

Check if the API server is running and accessible.

Endpoint

GET /auth/status

Response

{
  "authenticatedWith": "BASIC"
}

{
  "authenticatedWith": "APIKEY",
  "apiKeyAccess": [
    {
      "chainId": 1,
      "relayers": ["0x123...", "0x456..."]
    },
    {
      "chainId": 137,
      "relayers": ["0x789..."]
    }
  ]
}

Example

Basic Auth

curl https://your-rrelayer.com/auth/status \
  -u "username:password"

API Key Auth

curl https://your-rrelayer.com/auth/status \
  -H "x-rrelayer-api-key: your-api-key"

Will throw a 401 http error if none or valid.

Health Check

Check if the API server is running.

Endpoint

GET /health

Response

"healthy"

Example

curl https://your-rrelayer.com/health

This endpoint does not require authentication and returns a simple "healthy" string when the server is operational.

Rate Limiting Headers

When using rate limiting, include the rate limit key header:

x-rrelayer-rate-limit-key: <rate-limit-key>

Example:

curl https://your-rrelayer.com/transactions/relayers/0x.../send \
  -H "x-rrelayer-rate-limit-key: user-12345" \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{"to": "0x...", "value": "1000000000000000000"}'

You can config this here.

Development vs Production

Development Setup

For local development, you can use simple credentials:

api_config:
  authentication_username: 'admin'
  authentication_password: 'password'

Production Setup

For production, use strong, randomly generated credentials:

api_config:
  authentication_username: '${RRELAYER_AUTH_USERNAME}'
  authentication_password: '${RRELAYER_AUTH_PASSWORD}'

Set environment variables:

export RRELAYER_AUTH_USERNAME="admin_$(openssl rand -hex 16)"
export RRELAYER_AUTH_PASSWORD="$(openssl rand -base64 32)"