Why do I need an IndyKite environment?

IndyKite is a real-time data retrieval and enforcement platform that enables context-aware authorization and identity management. Before you can use any IndyKite capability, you need to set up an environment that:

• Stores your data: The Identity Knowledge Graph (IKG) holds nodes and relationships representing your entities.
• Authenticates your application: Credentials identify your application and authorize API calls.
• Enforces policies: Authorization rules are evaluated against data in your IKG.
• Isolates your project: Each project has its own IKG, ensuring data separation.

What is the IndyKite platform hierarchy?

IndyKite uses a hierarchical structure to organize resources. Understanding this hierarchy is essential for setting up your environment correctly.

Level	Component	Purpose	What it contains
1	Organization	Top-level account container	Service Accounts, Projects
2	Service Account	Config API authentication	Credentials for managing configurations
3	Project	Isolated working environment	Own IKG, Applications, Policies, Knowledge Queries
4	Application	Represents your software system	Application Agents
5	Application Agent	API authentication identity	Credentials (tokens) for API calls

What is an Organization?

An Organization is your top-level account in IndyKite. It is created when you sign up for the platform.

What does an Organization contain?

• Service Accounts: Credentials for managing configurations via the Config API.
• Projects: Isolated environments with their own Identity Knowledge Graphs.
• Organization ID: Unique identifier used when creating resources programmatically.

Why does the Organization matter?

The Organization establishes your account boundary and billing scope. All resources you create belong to your Organization, and Service Account credentials are created at this level.

What is a Service Account?

A Service Account provides credentials for the Config API, which manages IndyKite configurations.

What can I do with Service Account credentials?

• Create, read, update, and delete Projects
• Create Applications and Application Agents
• Create and manage KBAC policies
• Create and manage Knowledge Queries (CIQ)
• Configure External Data Resolvers
• Configure Trust Score Profiles
• Configure Token Introspection
• Configure Outbound Events
• Use Terraform to manage configurations as code

How do I create Service Account credentials?

1. Log in to the IndyKite Hub at your Organization level.
2. Navigate to Service Accounts.
3. Create a new Service Account.
4. Generate credentials for the Service Account.
5. Download the credentials JSON file.

Hub: https://eu.hub.indykite.com/service-accounts

How do I use Service Account credentials?

For REST API calls:

Extract the token field from your credentials file and use it in the Authorization header:

Authorization: Bearer <token-from-credentials-file>

For Terraform:

Set the environment variable:

export INDYKITE_SERVICE_ACCOUNT_CREDENTIALS_FILE=/path/to/credentials.json

What is a Project?

A Project (also called Application Space) is an isolated working environment with its own Identity Knowledge Graph.

What does a Project contain?

• Identity Knowledge Graph (IKG): A Neo4j graph database storing your nodes and relationships.
• Applications: Software systems that interact with the IKG.
• Authorization Policies: KBAC rules that govern access to data.
• Knowledge Queries: CIQ queries that read or modify graph data.
• External Data Resolvers: Configurations for fetching data from external APIs during query execution.
• Trust Score Profiles: Configurations for assessing data quality based on freshness, origin, and verification.
• Token Introspect configurations: Rules for validating external access tokens.
• Outbound Event configurations: Settings for streaming events to external systems.

Why is the IKG important?

The Identity Knowledge Graph is the foundation of IndyKite. All authorization decisions, data queries, and contextual operations are performed against data in your IKG. Before using any IndyKite product, you must capture data into your IKG.

What IKG options do I have?

Option	Description	Best for
Managed IKG	IndyKite hosts and manages the graph database	Quick start, no database management
Bring Your Own DB	Connect your own Neo4j database	Existing Neo4j investment, custom requirements

For managed IKG, specify the ikg_size and region when creating the project.

For your own database, provide the db_connection with URL, username, password, and database name.

How do I create a Project?

Option 1: Hub UI

1. Navigate to your Organization in the Hub.
2. Click "Create Project".
3. Enter project name and IKG configuration.
4. Save the project.

Option 2: REST API

Use the Config API with Service Account credentials:

Endpoint: https://openapi.indykite.com/api-documentation-config

Option 3: Terraform

Use the indykite_application_space resource:

Example: Environment Configuration Terraform

What is an Application?

An Application represents your software system within a Project. It serves as a container for Application Agents.

Why do I need an Application?

• Logical grouping: Organize multiple agents (e.g., backend, mobile, web) under one application.
• _Application node: When created, an _Application node is automatically added to your IKG.
• Service identity: The Application can act as a subject in CIQ queries without a user access token.

How do I create an Application?

Create an Application within your Project using the Hub UI, REST API, or Terraform. The indykite_application resource requires an app_space_id (Project ID).

What is an Application Agent?

An Application Agent is the identity that authenticates your API calls. Each agent has credentials (tokens) used to access IndyKite APIs.

What APIs can I call with Application Agent credentials?

API	Purpose	Required API permission
Capture API	Store nodes and relationships in the IKG	Capture
CIQ Execute API	Run Knowledge Queries to read/update graph data, and resolve the end-user token's IKG subject (GET /contx-iq/v1/whoami)	ContXIQ
Authorization API (AuthZEN)	Evaluate KBAC policies for access decisions and search allowed actions, resources, and subjects	Authorization
Policy listing	Read the project's active KBAC policies as stored (GET /access/v1/policies)	ReadAuthZConfigs
Data Schema API	Read the observed schema of the IKG (GET /data-schema/v1/)	ReadDataSchema
Token Introspect API	Validate access tokens and retrieve identity data	Applied automatically when a request carries a user access token
EntityMatching API	Resolve and match identities	EntityMatching

What API permissions can an Application Agent have?

Each Application Agent carries an api_permissions list, set when the agent is created (POST /configs/v1/application-agents) or updated (PUT /configs/v1/application-agents/{id}) and in the Hub. The agent can only call the APIs whose permission it holds; any other call fails with 401 and the message insufficient API access level for appAgent. The accepted values are:

Permission	What it lets the agent do	Endpoints
Authorization	Ask for access decisions and discover what is allowed. Covers the single and batch AuthZEN evaluations plus the three search endpoints that list the actions, resources, or subjects a policy permits. This is the permission a Policy Enforcement Point needs.	POST /access/v1/evaluation POST /access/v1/evaluations POST /access/v1/search/action POST /access/v1/search/resource POST /access/v1/search/subject
Capture	Write to the IKG directly: upsert and delete nodes, relationships, properties, and property metadata in batches. Meant for ingestion pipelines and back-office sync jobs; the writes are not policy-mediated.	Everything under /capture/v1/
ContXIQ	Run Knowledge Queries, so the agent can read or change graph data on behalf of a user or of the _Application subject, with a CIQ policy deciding what each caller may see or do. Also resolves a user token to its IKG subject through whoami. This is the permission a front end or API proxy needs.	POST /contx-iq/v1/execute GET /contx-iq/v1/whoami
EntityMatching	Run entity matching pipelines to find and merge records that describe the same real-world identity across sources.	Everything under /entity-matching/v1/
ReadAuthZConfigs	Read the project's active KBAC policies as they are stored, with their tags, optionally filtered by subject type. Read-only: no creation, update, or deletion, which stay on the Config API with Service Account credentials. Independent of Authorization: an agent that only makes decisions does not need it, and an agent that holds only this one can read the rules but not evaluate them.	GET /access/v1/policies
ReadDataSchema	Read the observed schema of the IKG: node types with their properties and value types, and the relationship combinations between them, with counts but no data. Used before writing Cypher for policies and Knowledge Queries, or to verify an ingest landed.	GET /data-schema/v1/

Grant only what the agent needs. Typical combinations: an ingestion job holds Capture; a backend that enforces access holds Authorization; a user-facing service that runs Knowledge Queries holds ContXIQ; an admin or AI-agent tool that inspects the rules and the schema holds ReadAuthZConfigs and ReadDataSchema. Permissions are set per agent and are not shared between agents of the same Application, so a permission an agent should gain later has to be added to that agent explicitly. The example below grants all six:

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

How do I create Application Agent credentials?

1. Create an Application Agent under your Application.
2. Generate credentials for the Application Agent.
3. Download or copy the credential token.

How do I use Application Agent credentials?

Include the token in your HTTP request header:

X-IK-ClientKey: <token-from-credentials-file>

What is the complete environment creation workflow?

To create a working IndyKite environment from scratch:

Step	Action	Result
1	Sign up for IndyKite Sandbox	Organization created
2	Create Service Account credentials	Config API access enabled
3	Create a Project with IKG	Isolated environment with graph database
4	Create an Application	_Application node added to IKG
5	Create Application Agent + credentials	API access enabled for your application
6	Capture data into the IKG	Nodes and relationships stored
7	Create policies and queries	Authorization and data access configured

What credentials do I need for what?

Different IndyKite APIs require different credentials:

Operation	Credential Type	Header
Create/manage configurations (Config API)	Service Account	Authorization: Bearer <token>
Capture data	AppAgent	X-IK-ClientKey: <token>
Execute CIQ queries	AppAgent	X-IK-ClientKey: <token>
AuthZEN evaluation	AppAgent	X-IK-ClientKey: <token>
User-context operations	AppAgent + User Access Token	X-IK-ClientKey + Authorization: Bearer
Terraform	Service Account	Environment variable

Which API regions are available?

IndyKite provides API endpoints in two regions:

• EU Region: https://eu.api.indykite.com
• US Region: https://us.api.indykite.com

Choose the region that matches your data residency requirements and Hub instance.

To learn how to control where your IKG data physically lives like choosing a project region, adding a read replica, routing nodes to specific locations with a composite database, and location-aware authorization: see the Data Residency & Composite Databases Guide.

How can I automate environment creation?

Option 1: Developer Hub Quick Start Script

The fastest way to set up a complete environment:

https://github.com/indykite/developer-hub/tree/master/get-started

The script creates:

• Project, Application, and Application Agent with credentials
• Sample data captured in the IKG
• KBAC and CIQ policies
• Verification tests

Option 2: Terraform

Manage your environment as infrastructure-as-code:

• Terraform Guide: https://developer.indykite.com/guides/guide-terraform
• Environment Configuration: terraform-2
• Terraform Provider: IndyKite Terraform Provider

Option 3: REST API

Programmatically create resources using the Config API:

Config API Reference

What should I do after creating an environment?

Once your environment is ready:

1. Capture data: Use the Capture API to store nodes and relationships in your IKG.
2. Create authorization policies: Define KBAC rules for access control.
3. Create Knowledge Queries: Define CIQ queries for data retrieval and updates.
4. Test your integration: Use the AuthZEN API or CIQ Execute API to verify your setup.

Next Steps

• Quick Start: Sandbox Guide
• Credentials: Credentials Guide
• Terraform: Terraform Guide
• Authorization: Dynamic Authorization Guide
• CIQ: ContX IQ Guide
• External Data Resolver: Fetch data from external APIs
• Trust Score: Assess data quality
• AuthZEN: AuthZEN Guide
• Examples: Developer Hub Resources
• API Reference: OpenAPI Documentation