Skip to main content

Authentication

⚠️ Future Content: The comprehensive technical authentication details and advanced security patterns below will be provided in future documentation updates. Enterprise authentication integrations and advanced security configurations are being developed for production environments.

Learn how to securely authenticate with the Filedgr API using API keys, access tokens, and various authentication patterns.

Overview​

Filedgr uses a two-step authentication process:

  1. API Key Authentication - Exchange your API key and secret for an access token
  2. Bearer Token Authorization - Use the access token to authenticate API requests

This approach provides both security and flexibility while keeping your API secret safe.

API Keys​

Generating API Keys​

  1. Log in to your Filedgr Dashboard
  2. Navigate to Settings → Developer → API Keys
  3. Click Create API Key
  4. Choose your key permissions and environment
  5. Copy and securely store your API Key and API Secret

API Key Types​

Production Keys​

  • Used for live applications and real blockchain transactions
  • Full access to all platform features
  • Transactions may incur blockchain fees

Test Keys​

  • Safe environment for development and testing
  • No blockchain fees or real transactions
  • Full feature parity with production

Key Permissions​

Configure what your API keys can access:

  • Read Only - View vaults, templates, and data
  • Read/Write - Create and modify vaults and data
  • Admin - Full account access including user management
  • Custom - Granular permissions for specific resources

Access Token Authentication​

Request Access Token​

Exchange your API credentials for a short-lived access token:

curl -X POST "https://api.filedgr.io/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "fgr_live_1234567890abcdef",
    "apiSecret": "fgs_live_0987654321fedcba"
  }'

Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "read write admin"
}

Token Properties​

  • accessToken - JWT token for API authentication
  • tokenType - Always "Bearer" for API requests
  • expiresIn - Token lifetime in seconds (default: 1 hour)
  • scope - Permissions granted to this token

Using Access Tokens​

Include the access token in the Authorization header:

curl -X GET "https://api.filedgr.io/vaults" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Management​

Token Refresh​

Access tokens expire after 1 hour. Request a new token before expiration:

class FiledgrAuth {
  constructor(apiKey, apiSecret) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.accessToken = null;
    this.expiresAt = null;
  }

  async getToken() {
    if (!this.accessToken || Date.now() >= this.expiresAt) {
      await this.refreshToken();
    }
    return this.accessToken;
  }

  async refreshToken() {
    const response = await fetch('https://api.filedgr.io/auth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        apiKey: this.apiKey,
        apiSecret: this.apiSecret
      })
    });

    const data = await response.json();
    this.accessToken = data.accessToken;
    this.expiresAt = Date.now() + (data.expiresIn * 1000) - 60000; // 1 min buffer
  }
}

Token Validation​

Verify a token's validity and inspect its claims:

curl -X GET "https://api.filedgr.io/auth/validate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "valid": true,
  "expiresAt": "2024-01-15T11:30:00Z",
  "scope": "read write",
  "apiKeyId": "fgr_live_1234567890abcdef",
  "userId": "user_abc123"
}

SDK Authentication​

JavaScript SDK​

import { Filedgr } from '@filedgr/sdk';

const filedgr = new Filedgr({
  apiKey: process.env.FILEDGR_API_KEY,
  apiSecret: process.env.FILEDGR_API_SECRET,
  environment: 'production' // or 'test'
});

// SDK handles token management automatically
const vaults = await filedgr.vaults.list();

Python SDK​

import os
import filedgr

client = filedgr.Client(
    api_key=os.environ['FILEDGR_API_KEY'],
    api_secret=os.environ['FILEDGR_API_SECRET'],
    environment='production'
)

# Automatic token refresh
vaults = client.vaults.list()

Go SDK​

package main

import (
    "os"
    "github.com/filedgr/go-sdk"
)

func main() {
    client := filedgr.NewClient(&filedgr.Config{
        APIKey:      os.Getenv("FILEDGR_API_KEY"),
        APISecret:   os.Getenv("FILEDGR_API_SECRET"),
        Environment: "production",
    })

    vaults, err := client.Vaults.List(nil)
    if err != nil {
        log.Fatal(err)
    }
}

Webhook Authentication​

Webhook Signatures​

Filedgr signs webhook payloads with your webhook secret:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Express middleware
app.use('/webhooks/filedgr', (req, res, next) => {
  const signature = req.headers['x-filedgr-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  
  next();
});

Webhook Headers​

POST /your-webhook-endpoint
Content-Type: application/json
X-Filedgr-Signature: sha256=abc123...
X-Filedgr-Event-Type: vault.data_updated
X-Filedgr-Delivery-ID: uuid4

Security Best Practices​

Environment Variables​

Never hardcode credentials in your source code:

# .env file
FILEDGR_API_KEY=fgr_live_1234567890abcdef
FILEDGR_API_SECRET=fgs_live_0987654321fedcba
FILEDGR_WEBHOOK_SECRET=whsec_1234567890abcdef

Credential Rotation​

Regularly rotate your API keys:

  1. Generate new API key in dashboard
  2. Update environment variables in production
  3. Test with new credentials
  4. Delete old API key

Network Security​

  • Use HTTPS for all API requests
  • Implement proper firewall rules
  • Consider IP allowlisting for production keys
  • Use VPN for sensitive operations

Error Handling​

Don't expose credentials in error logs:

try {
  const token = await auth.getToken();
} catch (error) {
  // ❌ Don't do this
  console.error('Auth failed:', error.response.data);
  
  // ✅ Do this instead  
  console.error('Authentication failed');
  logger.error('Auth error', { 
    message: error.message,
    statusCode: error.response?.status 
  });
}

Authentication Errors​

Common Error Responses​

Invalid API Key​

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked",
  "statusCode": 401
}

Expired Token​

{
  "error": "token_expired", 
  "message": "Access token has expired",
  "statusCode": 401
}

Insufficient Permissions​

{
  "error": "insufficient_permissions",
  "message": "API key does not have required permissions for this operation",
  "statusCode": 403
}

Rate Limited​

{
  "error": "rate_limited",
  "message": "Too many authentication requests",
  "statusCode": 429,
  "retryAfter": 60
}

Error Handling Strategy​

async function makeAuthenticatedRequest(url, options = {}) {
  let retries = 3;
  
  while (retries > 0) {
    try {
      const token = await auth.getToken();
      
      const response = await fetch(url, {
        ...options,
        headers: {
          'Authorization': `Bearer ${token}`,
          ...options.headers
        }
      });
      
      if (response.status === 401) {
        // Token might be expired, force refresh
        auth.clearToken();
        retries--;
        continue;
      }
      
      return response;
      
    } catch (error) {
      if (retries === 1) throw error;
      retries--;
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
}

Testing Authentication​

Unit Tests​

describe('Authentication', () => {
  it('should request token with valid credentials', async () => {
    const auth = new FiledgrAuth('test_key', 'test_secret');
    const token = await auth.getToken();
    
    expect(token).toBeDefined();
    expect(typeof token).toBe('string');
  });

  it('should handle invalid credentials', async () => {
    const auth = new FiledgrAuth('invalid', 'invalid');
    
    await expect(auth.getToken()).rejects.toThrow('invalid_api_key');
  });
});

Integration Tests​

# Test authentication endpoint
curl -X POST "https://api.filedgr.io/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "test_1234567890abcdef", 
    "apiSecret": "test_0987654321fedcba"
  }' \
  --fail --show-error

Next Steps​

Once you have authentication working:

  1. Create Your First Vault - Start building with vaults
  2. Explore Templates - Understand data structures
  3. Set Up Webhooks - Get real-time notifications
  4. Browse API Reference - Explore all available endpoints

For questions about authentication, reach out to our developer support team.