Bermuda Commercial Bank RESTful Open Banking API Implementation (v1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Creates new API client credentials based on an existing client's permissions and configuration. The new credentials will inherit the same roles and permissions as the specified existing client.

Key Features:

• A new client ID (GUID) is generated automatically
• A cryptographically secure password (22-30 characters) is generated automatically
• A cryptographically secure message signing secret (32 bytes) is generated automatically for HMAC-SHA256 signing
• All roles and direct permissions are copied from the existing client
• The new credentials can have different IP restrictions if specified

Password Security:

• Generated passwords are 22-30 characters long for enhanced security
• Include uppercase letters, lowercase letters, digits, and special characters
• The generated password is only returned once in the response

Message Signing Secret:

• A 32-byte (256-bit) random key (Base64 encoded) is generated for signing API requests
• This key will be used by the system to sign callback responses - notifications, background job webhooks
• The secret is returned only once in the response

Access Control:

• You can only create credentials based on clients you have access to
• New client inherits exact role and permission set from source client
• IP restrictions can be customized or inherited from source client

Base URL:

All API requests use the versioned base URL:

https://api.bcb.bm/v1/credentials

Idempotency

The API supports idempotency through the optional Idempotency-Key header:

• If no idempotency key is provided, the request is processed normally (duplicates are possible)
• If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results
• If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response
• Idempotency keys are user-specific - different users with the same keys don't share cached responses
• The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000").

Sample Request in JavaScript:

async function createCredentials() {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch('https://api.bcb.bm/v1/credentials', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        allowedIps: '192.168.1.100,10.0.0.0/24' // Optional: specify IP restrictions, or omit/'*' for all IPs
      })
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('New credentials created:', {
      clientId: data.clientId,
      clientSecret: data.clientSecret, // Save this securely - only shown once!
      messageSigningSecret: data.messageSigningSecret, // Save this securely - only shown once!
      isActive: data.isActive,
      allowedIps: data.allowedIps
    });
    
    // Store new credentials securely
    // WARNING: This is just an example - use secure storage in production
    localStorage.setItem('newClientId', data.clientId);
    localStorage.setItem('newClientSecret', data.clientSecret);
    localStorage.setItem('newMessageSigningSecret', data.messageSigningSecret);
    
  } catch (error) {
    console.error('Error creating credentials:', error);
  }
}

createCredentials();

Required Permission: manage-credentials

This endpoint requires the permission claim manage-credentials to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

Rotates (changes) the client secret AND the message signing secret for an existing API client while preserving all other settings. This is useful for credential rotation policies, security incident response, or regular maintenance.

Key Features:

• A new cryptographically secure password (22-30 characters) is generated automatically
• A new cryptographically secure message signing secret (32 bytes) is generated automatically
• The existing client's secrets are immediately replaced with the new ones
• All roles, permissions, and other settings remain unchanged
• The old secrets become invalid immediately after successful rotation
• The new secrets are returned in the response (only shown once)

Password Security:

• Generated passwords are 22-30 characters long for enhanced security
• Include uppercase letters, lowercase letters, digits, and special characters
• The new password is only returned once in the response

Access Control:

• You can only rotate secrets for clients you have access to
• The rotated client retains all existing roles and permissions

Important Security Notes:

• The old secret stops working immediately after successful rotation
• Any applications using the old secret will need to be updated with the new secret
• Store the new secret securely as it won't be shown again

Base URL:

All API requests use the versioned base URL:

https://api.bcb.bm/v1/credentials/{clientId}

Idempotency

The API supports idempotency through the optional Idempotency-Key header:

• If no idempotency key is provided, the request is processed normally (duplicates are possible)
• If a valid UUID idempotency key is provided for a new transaction, the system stores the key and associates it with the transaction results
• If the same idempotency key is received again for the same endpoint/action, the system returns the previously stored response
• Idempotency keys are user-specific - different users with the same keys don't share cached responses
• The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000").

Sample Request in JavaScript:

async function rotateClientSecret(clientId) {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}`, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('Client secret rotated successfully:', {
      clientId: data.clientId,
      newClientSecret: data.clientSecret, // Save this securely - only shown once!
      newMessageSigningSecret: data.messageSigningSecret, // Save this securely - only shown once!
      isActive: data.isActive,
      allowedIps: data.allowedIps
    });
    
    // Update stored credentials securely
    // WARNING: This is just an example - use secure storage in production
    localStorage.setItem('clientSecret', data.clientSecret);
    localStorage.setItem('messageSigningSecret', data.messageSigningSecret);
    
    // Important: Update any applications using the old secret
    console.warn('IMPORTANT: Update all applications using this client with the new secret!');
    
  } catch (error) {
    console.error('Error rotating client secret:', error);
  }
}

// Example usage
rotateClientSecret('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

This endpoint requires the permission claim manage-credentials to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

Disables an existing API client, immediately preventing any further authentication using that client ID and secret. This operation also revokes all active tokens associated with the client.

Key Features:

• Disables the credentials instantly – all authentication requests will fail after this operation
• Revokes all active tokens immediately for enhanced security
• Idempotent: calling the endpoint on an already inactive client returns success

Security Considerations:

• All active tokens are immediately invalidated and removed from the system
• Any applications using the disabled client will lose access immediately
• The client record is preserved for audit and compliance purposes

Access Control:

• You can only disable clients that belong to your organization

Base URL:

All API requests use the versioned base URL:

https://api.bcb.bm/v1/credentials/{clientId}

Sample Request in JavaScript:

async function disableClient(clientId) {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}`, {
      method: 'DELETE',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const data = await response.json();
    console.log('Client disabled successfully:', {
      clientId: data.clientId,
      isActive: data.isActive, // Should be false
      allowedIps: data.allowedIps
    });
    
    // Important: Update any applications that were using this client
    console.warn('IMPORTANT: All applications using this client will lose access immediately!');
    
  } catch (error) {
    console.error('Error disabling client:', error);
  }
}

// Example usage
disableClient('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

This endpoint requires the permission claim manage-credentials to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

Retrieves all permissions assigned to the specified API client. The response provides a comprehensive view of what features the client can access.

Key Features:

• Returns all permissions assigned to the client
• Results are sorted alphabetically by permission key for consistent ordering
• Includes human-readable descriptions for each permission

Access Control:

• You can only view permissions for clients that belong to your organization

Use Cases:

• Audit client access capabilities
• Troubleshoot authentication and authorization issues
• Verify client configuration during security reviews
• Document client permissions for compliance purposes

Base URL:

All API requests use the versioned base URL:

https://api.bcb.bm/v1/credentials/{clientId}/permissions

Sample Request in JavaScript:

async function getClientPermissions(clientId) {
  try {
    const token = localStorage.getItem('jwt'); // Your JWT token from authentication
    
    const response = await fetch(`https://api.bcb.bm/v1/credentials/${clientId}/permissions`, {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Error: ${errorData.message || response.statusText}`);
    }
    
    const permissions = await response.json();
    console.log('Client permissions:', permissions);
    
    // Display permissions in a user-friendly format
    permissions.forEach(permission => {
      console.log(`- ${permission.key}: ${permission.description || 'No description available'}`);
    });
    
    return permissions;
    
  } catch (error) {
    console.error('Error retrieving client permissions:', error);
  }
}

// Example usage
getClientPermissions('12345678-1234-1234-1234-123456789abc');

Required Permission: manage-credentials

This endpoint requires the permission claim manage-credentials to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.