Set Up IndyKite Environment: Project, Application, and Credentials

This guide walks through the complete environment setup process:

1. Create a Project - the top-level container for your IndyKite resources

2. Create an Application - represents your software that will interact with IndyKite

3. Create an Application Agent - the identity used for API authentication

4. Generate Application Agent Credentials - the API key for authentication

5. Configure Token Introspect - enables token validation for your application

Complete these steps before using any other IndyKite feature (IKG, ContX IQ, KBAC, etc.).

Use case

Scenario: You are setting up a new application that needs to:

- Store identity and resource data in the IndyKite Knowledge Graph (IKG)

- Use ContX IQ for authorized data queries

- Use KBAC for access control decisions

Before any of these features work, you must create the environment hierarchy:

Organization (already exists) -> Project -> Application -> Application Agent -> Credentials

Requirements

Prerequisites:

- ServiceAccount credentials: Created in IndyKite Hub or via REST API for your Organization

- Organization ID: Your IndyKite organization identifier

Required API access:

- POST /configs/v1/projects (create project)

- POST /configs/v1/applications (create application)

- POST /configs/v1/application-agents (create agent)

- POST /configs/v1/application-agent-credentials (generate credentials)

- POST /configs/v1/token-introspects (configure token validation)

Steps

Step 1: Create a Project

- Authentication: ServiceAccount credential as Bearer token in Authorization header

- Action: POST to /configs/v1/projects with project name and configuration

- Input: Organization ID, project display name, optional BYODB (Bring Your Own Database) configuration

- Result: Project ID returned for use in subsequent steps

Step 2: Create an Application

- Authentication: ServiceAccount credential as Bearer token

- Action: POST to /configs/v1/applications

- Input: Project ID from Step 1, application display name

- Result: Application ID returned

Step 3: Create an Application Agent

- Authentication: ServiceAccount credential as Bearer token

- Action: POST to /configs/v1/application-agents

- Input: Application ID from Step 2, agent display name

- Result: Application Agent ID returned

Step 4: Generate Application Agent Credentials

- Authentication: ServiceAccount credential as Bearer token

- Action: POST to /configs/v1/application-agent-credentials

- Input: Application Agent ID from Step 3

- Result: Credential JSON containing the API key (X-IK-ClientKey value)

- Important: Save these credentials securely - they cannot be retrieved again

Step 5: Download Credentials

- Action: Save the credential JSON from Step 4 to a secure location

- Use: This credential is used as the X-IK-ClientKey header for data ingestion and query execution

Step 6: Configure Token Introspect

- Authentication: ServiceAccount credential as Bearer token

- Action: POST to /configs/v1/token-introspects

- Input: Application Agent ID, token validation settings

- Result: Token introspect configuration ID returned

{
  "db_connection": {
    "password": "example-password",
    "url": "neo4j+s://xxxxxxxx.databases.neo4j.io",
    "username": "neo4j"
  },
  "description": "Project description",
  "display_name": "Project name",
  "ikg_size": "2GB",
  "name": "project-name",
  "organization_id": "gid-of-organization",
  "region": "us-east1"
}

{
  "description": "Application description",
  "display_name": "Application name",
  "name": "app-name",
  "project_id": "gid-of-project"
}

{
  "api_permissions": [
    "Authorization",
    "Capture",
    "ContXIQ",
    "EntityMatching"
  ],
  "application_id": "gid-of-application",
  "description": "App Agent description",
  "display_name": "App Agent name",
  "name": "app-agent-name"
}

{
  "application_agent_id": "gid-of-app-agent",
  "display_name": "AppAgent Credentials name",
  "expire_time": "2026-12-31T12:34:56-01:00"
}

{
  "claims_mapping": {
    "email": {
      "selector": "email"
    },
    "name": {
      "selector": "full_name"
    }
  },
  "description": "Token introspect description",
  "display_name": "Token introspect name",
  "ikg_node_type": "Person",
  "jwt_matcher": {
    "audience": "audience-id",
    "issuer": "https://example.com"
  },
  "name": "rest-token-introspect",
  "online_validation": {
    "cache_ttl": 600
  },
  "perform_upsert": true,
  "project_id": "gid-of-project"
}