Who This Is For / When to Use
Use Private Integrations if you need a secure, long-lived API token for a custom or internal integration without implementing OAuth2 flows.
What Is a Private Integration?
A Private Integration is a Kyrios-managed integration that generates a static access token tied to specific scopes (permissions). The token is used by developers to authenticate API v2.0 requests.
Private Integrations are:
Generated and managed from the Kyrios UI
Scope-restricted for least-privilege access
Compatible with API v2.0 features, including webhooks
Private Integrations vs API Keys
Private Integrations replace legacy API Keys with a more secure model:
Scoped access instead of full account access
Admin-controlled lifecycle (rotate, expire, revoke)
Uses the latest API version (v2.0)
Private Integrations vs OAuth2 Access Tokens
Private Integrations are static equivalents of OAuth2 access tokens.
Private Integrations | OAuth2 Access Tokens |
Generated in UI | Generated programmatically |
Static until rotated | Refreshed daily |
Simple to manage | Requires OAuth flow |
Where to Find Private Integrations
Navigate to Settings → Other Settings → Private Integrations.
Creating a Private Integration
Step 1: Start a New Integration
Click Create New Integration.
Step 2: Enter Basic Information
Provide a clear name and description.
Step 3: Select Scopes (Permissions)
Choose only the permissions the integration needs.
Step 4: Generate and Copy the Token
After creation, copy the generated token immediately.
Important: The token is shown only once. Store it securely.
Using the Private Integration Token
Include the token in the Authorization header of API requests.
Example:
curl --request GET \ --url https://services.yourdomain.com/contacts/{contactId} \ --header 'Accept: application/json' \ --header 'Authorization: <YOUR PRIVATE INTEGRATION TOKEN>' \ --header 'Version: 2021-07-28'
Managing Tokens
Rotate and Expire Token Later
Creates a new token and keeps the old token active for 7 days.
Rotate and Expire Token Now
Immediately invalidates the existing token and issues a new one.
Cancel a Scheduled Rotation
Stops a pending token rotation.
Responding to a Compromised Token
Open the Private Integration.
Rotate and expire the token immediately.
Update the token in the third-party app.
Editing an Existing Integration
You can update the name, description, or scopes without generating a new token.
Updating integration details does not rotate the token.
Deleting a Private Integration
Delete an integration when it is no longer needed.
Permissions Required to Manage Private Integrations
By default, admins can manage Private Integrations. Permissions can be customized under Roles & Permissions.
Security Best Practices
Rotate tokens every 90 days
Use the minimum required scopes
Never share tokens publicly
Expire tokens immediately if compromised
FAQs
What is a Private Integration?
A secure way to connect Kyrios to third-party apps using scoped API tokens.
Who can create Private Integrations?
Admins by default. Permissions are configurable.
Can I edit scopes without changing the token?
Yes. Scope updates do not regenerate tokens.
How often should I rotate tokens?
Every 90 days is recommended.
What’s the difference between rotate and expire?
Rotate creates a new token. Expire immediately invalidates the current one.