Skip to main content
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
2
Store it securely as an environment variable:
export DEFINITE_API_KEY="your-api-key-here"