Overview
Setting up a custom integration involves two main steps:
Creating an API Key - Generate secure credentials for authentication
Configuring Your Integration - Define which data you'll submit and receive the schemas and endpoints
Part 1: Creating an API Key
Before you can submit data through a custom integration, you'll need to create an API key for authentication.
Accessing API Keys
Navigate to Settings > Company Settings > API Keys to view and manage your API keys.
Here you can:
View all active API keys
See when each key was created and when it expires
Create new keys
Revoke existing keys
Creating a New API Key
Step 1: Enter Key Details
Click Create new API Key to open the creation dialog.
You'll need to provide:
Key Name: A descriptive name to help you identify this key (e.g., "Production Integration")
Expires On: Choose when this key should expire.
Step 2: Copy Your API Key
Once created, your API key will be displayed one time only. Use the visibility toggle (eye icon) to show/hide your API key.
Important: Copy and securely store your API key immediately. You won't be able to view it again after closing this dialog. If you lose your key, you'll need to create a new one.
Revoking an API Key
If you need to revoke a key (for example, if it's been compromised), click on Revoke.
Confirm the action by clicking Revoke API Key, and the key will be immediately invalidated. Any requests using this key will be rejected.
Part 2: Setting Up a Custom Integration
Accessing Integrations
Navigate to the Integrations page from the site menu to view all your integrations.
Creating a Custom Integration
Click + Custom Integration to launch the setup wizard.
Step 1: Basic Details
Provide information about your integration and click Next.
Integration Name: A name for your integration (e.g., "In-house HR System") - Mandatory.
Integration Description: A brief description of what this integration does.
Logo: Upload a logo image to help identify your integration visually.
Step 2: Select Monitorings
Choose which monitorings you want to submit through this integration (use the categories on the left hand side to select them) and click Next. Selecting at least one monitoring is required.
Alternatively, you can go back to Basic Details to make changes by clicking on it.
Browse available monitorings by category or search for specific ones. Select all the monitorings you plan to submit.
Step 3: Review Integration Setup
Review the schemas for your selected monitorings.
This step displays the JSON schemas that define the structure your data must follow. You can expand each schema to review the requirements.
Click Finish to create your integration. Alternatively, go back to Basic Details or Select Monitoring to make changes by clicking on them.
Viewing Integration Details
After creation, you'll be taken to your integration's detail page where you'll find all the information needed to submit data.
On this page, you can:
View all schemas for your selected monitorings’ contexts.
Access the API endpoints for each monitoring context
Review required headers for authentication
Validate your JSON data against schemas
Edit your monitoring selection via the Monitoring tab
Note: Editing your monitoring selection will update the available schemas and endpoints shown on this page. Add or remove monitorings as your integration needs evolve.
Viewing integration monitoring selection
There is also a Monitoring tab that you can use to view and edit your integration’s connected monitoring.
On this page, you can:
Click on any monitoring to view more details in the Control Center
Add and remove connected monitorings by clicking Edit Monitoring.
View your monitoring selection’s schemas and integration API details via the JSON Sample tab.
Where to find your integration
To view your custom integration, in the main menu, click Integrations, go to the Connected tab, and use search for your integration’s name or select the Custom Integrations category.
Click on your integration’s card to view its details.
Understanding Schemas and Submitting Data
This is where we'll walk through a complete example to clarify how schemas relate to your API requests.
Example: HR Integration
Let's say you've created an integration that submits two monitoring contexts:
Employee records
User access records
Your Integration Details
Integration ID (example): 68da8236e5158bfd0be9e639
Note: When you copy endpoints from the integration details page, your integration ID is automatically included in the URL.
API Endpoints
You'll have one endpoint per monitoring context:
POST <https://api.scytale.ai/external/v2/integration/68da8236e5158bfd0be9e639/context/list_employees>
POST <https://api.scytale.ai/external/v2/integration/68da8236e5158bfd0be9e639/context/list_users>
Required Headers
All requests must include these headers:
Content-Type: application/json
x-api-key: YOUR_API_KEY_HERE
Replace YOUR_API_KEY_HERE with the API key you created in Part 1.
Understanding Schemas
A schema defines the structure of individual records in your data. Think of it as a template for a single employee or a single user.
Employee Schema
{
"type": "object",
"title": "Employee",
"description": "Schema for employee record",
"properties": {
"employee_name": {
"type": "string",
"description": "Full name of the employee"
},
"email": {
"type": "string",
"description": "Email address of the employee",
"format": "email"
},
"job_title": {
"type": "string",
"description": "Job title of the employee"
},
"manager": {
"type": "string",
"description": "Manager of the employee"
},
"hiring_date": {
"type": "string",
"format": "date-time",
"description": "Hiring date of the employee"
},
"termination_date": {
"type": "string",
"format": "date-time",
"description": "Termination date if applicable"
},
"employment_type": {
"type": "string",
"description": "Type of employment"
},
"employment_status": {
"type": "string",
"description": "Current status of employment"
},
"id": {
"type": "string",
"description": "Unique identifier of the employee"
},
"first_name": {
"type": "string",
"description": "First name of the employee"
},
"last_name": {
"type": "string",
"description": "Last name of the employee"
},
"employment_status_normalized": {
"type": "string",
"description": "Normalized employment status"
},
"department": {
"type": "string",
"description": "Department of the employee"
},
"lifecycle_status": {
"type": "string",
"description": "Lifecycle status of the employee"
}
},
"required": ["id"]
}Key Points:
The schema describes what fields can appear in one employee record
Only
idis required; other fields are optionalFields like
emailmust follow specific formats (e.g., valid email address)Date fields should use ISO date-time format (e.g.,
2024-01-15T09:30:00Z)
User Access Schema
{
"type": "object",
"title": "UserAccessRecordSchema",
"description": "Schema for a user's access record within a company/account.",
"properties": {
"account_project_id": {
"type": "string",
"description": "ID of the account or project."
},
"username": {
"type": "string",
"description": "User's login name."
},
"identifier": {
"type": "string",
"description": "User's unique identifier (e.g., ARN or equivalent)."
},
"role": {
"type": "array",
"description": "Roles or policies assigned to the user.",
"items": {
"type": "string"
},
"uniqueItems": true
},
"groups": {
"type": "array",
"description": "Groups the user belongs to.",
"items": {
"type": "string"
},
"uniqueItems": true
},
"is_admin": {
"type": "boolean",
"description": "Whether the user has admin privileges."
},
"email": {
"type": "string",
"format": "email",
"description": "User's email address."
}
},
"required": ["account_project_id", "username", "identifier"]
}Key Points:
Three fields are required:
account_project_id,username, andidentifierroleandgroupsare arrays of stringsis_adminis a boolean (true/false)
Constructing API Requests
Important: The schema describes individual records. When submitting data, you wrap your records in a data array.
Request Body Structure
All requests follow this structure:
{
"data": [
{/* first record matching the schema */},
{/* second record matching the schema */},
{/* ... more records ... */}
]
}
Complete Request Examples
Example 1: Submitting Employee Records
Endpoint:
POST <https://api.scytale.ai/external/v2/integration/68da8236e5158bfd0be9e639/context/list_employees>
Headers:
Content-Type: application/json
x-api-key: example_abcd1234567890
Request Body:
{
"data": [
{
"id": "emp_001",
"employee_name": "Sarah Johnson",
"first_name": "Sarah",
"last_name": "Johnson",
"email": "sarah.johnson@company.com",
"job_title": "Senior Software Engineer",
"department": "Engineering",
"manager": "John Smith",
"hiring_date": "2022-03-15T00:00:00Z",
"employment_type": "Full-time",
"employment_status": "Active",
"employment_status_normalized": "active",
"lifecycle_status": "employed"
},
{
"id": "emp_002",
"employee_name": "Michael Chen",
"first_name": "Michael",
"last_name": "Chen",
"email": "michael.chen@company.com",
"job_title": "Product Manager",
"department": "Product",
"manager": "Lisa Wang",
"hiring_date": "2021-07-01T00:00:00Z",
"employment_type": "Full-time",
"employment_status": "Active",
"employment_status_normalized": "active",
"lifecycle_status": "employed"
},
{
"id": "emp_003",
"employee_name": "Emily Rodriguez",
"first_name": "Emily",
"last_name": "Rodriguez",
"email": "emily.rodriguez@company.com",
"job_title": "Marketing Specialist",
"department": "Marketing",
"hiring_date": "2023-01-10T00:00:00Z",
"termination_date": "2023-12-15T00:00:00Z",
"employment_type": "Full-time",
"employment_status": "Terminated",
"employment_status_normalized": "terminated",
"lifecycle_status": "offboarded"
}
]
}Note: Each object in the data array represents one employee and must include at least the id field (the only required field). We've included additional fields to provide complete information.
Example 2: Submitting User Access Records
Endpoint:
POST <https://api.scytale.ai/external/v2/integration/68da8236e5158bfd0be9e639/context/list_users>
Headers:
Content-Type: application/json
x-api-key: example_abcd1234567890
Request Body:
{
"data": [
{
"account_project_id": "proj_123456",
"username": "sarah.johnson",
"identifier": "arn:aws:iam::123456789012:user/sarah.johnson",
"email": "sarah.johnson@company.com",
"role": [
"Developer",
"Team Lead"
],
"groups": [
"Engineering",
"Team-Alpha"
],
"is_admin": false
},
{
"account_project_id": "proj_123456",
"username": "michael.chen",
"identifier": "arn:aws:iam::123456789012:user/michael.chen",
"email": "michael.chen@company.com",
"role": [
"Product Owner"
],
"groups": [
"Product",
"Leadership"
],
"is_admin": true
},
{
"account_project_id": "proj_789012",
"username": "contractor_001",
"identifier": "arn:aws:iam::123456789012:user/contractor_001",
"role": [
"Viewer"
],
"groups": [
"Contractors"
],
"is_admin": false
}
]
}Note: Each object in the data array represents one user's access record. All three required fields (account_project_id, username, identifier) must be present. Optional fields like email, role, groups, and is_admin can be included when available.
Schema Validation
Before implementing your integration, you can validate your JSON data against the schema.
Note: The JSON file you upload for validation must follow the request body structure with a data array containing your records.
Each monitoring context has a schema with Validate functionality.
Clicking Validate opens the validation dialog where you can upload your JSON file by clicking Upload to Validate. Your JSON file needs to be in the same format as the Request Body.
After uploading, the section temporarily shows the status of your validation.
On the integration details page:
Click Validate next to any schema
Upload a JSON file containing your data in the request body structure.
We'll verify that your each item in your data array matches the schema requirements </aside>
This is helpful for testing your data structure before making actual API requests.
Common Questions
Q: What's the difference between the schema and the request body?
The schema describes the structure of one individual record (e.g., one employee, one user). The request body wraps an array of these records inside a data field. Think of it this way: the schema is the template, and your request body is a container for multiple items that follow that template.
Q: Do I need to include all fields from the schema?
No. Only fields marked as "required" in the schema must be included. Other fields are optional and can be omitted if you don't have that data.
Q: Can I submit data for multiple contexts in one request?
No. Each context (e.g., employees, users) has its own endpoint. You need to make separate requests for each monitoring.
Q: What happens if I submit invalid data?
The API will reject the request and return an error response indicating what's wrong with your data. Use the validation feature on the integration details page to test your data structure before implementing your integration.