The Custom integration type provides a flexible way to securely store credentials for any data source. All keys are automatically encrypted and can be accessed in your Python code using the Definite SDK.

Key Features

  • Flexible Key-Value Storage: Add unlimited secure credentials
  • Automatic Encryption: All values are encrypted at rest
  • Easy Access: Retrieve credentials using the Definite SDK

Creating a Custom Integration

1

Navigate to Settings Integrations. Search for and select “Custom” as the integration type.
Image 1 Pn
2

Enter a name for your integration (e.g., “Internal API Credentials”) and add your credentials:
  • Click +Add Secret to add a new credential
  • Enter a key name (alphanumeric with underscores, e.g., my_custom_integration)
  • Enter the secret value to be encrypted
  • Repeat for all credentials needed
Image 2 Pn
3

Click Save to create the integration with encrypted credentials.
Key Naming Rules: Keys must contain only letters, numbers, and underscores. They cannot start with a number or be empty.

Using in Python Code

Access your custom integration credentials using the Definite SDK:
from definite_sdk.client import DefiniteClient

# Initialize the client
client = DefiniteClient(DEFINITE_API_KEY)
integration_store = client.get_integration_store()

# Get your custom integration
custom_integration = integration_store.get_integration('my_custom_integration')

# Access individual secrets
api_key = custom_integration.secrets.get("api_key")
base_url = custom_integration.secrets.get("base_url")

# Use with any Python library
import requests

response = requests.get(
    f"{base_url}/api/data",
    headers={"Authorization": f"Bearer {api_key}"}
)

Common Use Cases

Internal APIs

Store credentials for proprietary APIs:
from definite_sdk.client import DefiniteClient

client = DefiniteClient(DEFINITE_API_KEY)
integration_store = client.get_integration_store()

internal_api = integration_store.get_integration('internal-systems')
token = internal_api.secrets.get("auth_token")
endpoint = internal_api.secrets.get("api_endpoint")

Database Connections

Secure database credentials:
from definite_sdk.client import DefiniteClient

client = DefiniteClient(DEFINITE_API_KEY)
integration_store = client.get_integration_store()

db_creds = integration_store.get_integration('custom-database')
connection_string = f"postgresql://{db_creds.secrets.get('username')}:{db_creds.secrets.get('password')}@{db_creds.secrets.get('host')}/{db_creds.secrets.get('database')}"

Third-Party Services

Any service not covered by built-in integrations:
from definite_sdk.client import DefiniteClient

client = DefiniteClient(DEFINITE_API_KEY)
integration_store = client.get_integration_store()

custom_service = integration_store.get_integration('external-service')
client_id = custom_service.secrets.get("client_id")
client_secret = custom_service.secrets.get("client_secret")

Working with Multiple Integrations

You can access multiple custom integrations in the same script:
from definite_sdk.client import DefiniteClient

client = DefiniteClient(DEFINITE_API_KEY)
integration_store = client.get_integration_store()

# Get multiple integrations
api_creds = integration_store.get_integration('api-credentials')
db_creds = integration_store.get_integration('database-credentials')
service_creds = integration_store.get_integration('third-party-service')

# Use credentials from different integrations
api_key = api_creds.secrets.get("api_key")
db_password = db_creds.secrets.get("password")
webhook_secret = service_creds.secrets.get("webhook_secret")

Best Practices

  1. Initialize Once: Create the DefiniteClient once and reuse it
  2. Group Related Credentials: Store related keys in the same integration
  3. Use Clear Names: Make integration and key names self-documenting
  4. Handle Missing Keys: Always check if keys exist before using them
  5. Secure API Keys: Store your DEFINITE_API_KEY as an environment variable. Your DEFINITE_API_KEY is automatically loaded in Python blocks on Definite.

Example with Error Handling

import os
from definite_sdk.client import DefiniteClient

# Get API key from environment
DEFINITE_API_KEY = os.getenv('DEFINITE_API_KEY')
if not DEFINITE_API_KEY:
    raise ValueError("DEFINITE_API_KEY environment variable not set")

# Initialize client
client = DefiniteClient(DEFINITE_API_KEY)
integration_store = client.get_integration_store()

try:
    # Get integration
    integration = integration_store.get_integration('my-custom-integration')
    
    # Safely access secrets
    api_key = integration.secrets.get("api_key")
    if not api_key:
        raise ValueError("api_key not found in integration")
        
    # Use the credentials
    # ... your code here ...
    
except Exception as e:
    print(f"Error accessing integration: {e}")

Security

  • All credential values are encrypted using AES-256 encryption
  • Keys are encrypted before storage and decrypted only when accessed
  • Access is controlled by Definite’s permission system
  • The DEFINITE_API_KEY controls access to integrations
  • Audit logs track all integration changes
Once saved, credential values cannot be viewed in the UI. Store them securely elsewhere if you need to reference the original values.

Getting Your Definite API Key

To use the Definite SDK, you’ll need an API key:
  1. On the Definite homepage, navigate to your username in the lower-left corner of the screen, then click Copy API Key. The API Key will be automatically copied to your clipboard.
Image 3 Pn
  1. Store it securely as an environment variable:
export DEFINITE_API_KEY="your-api-key-here"