This guide explains the authentication components required to access the IndyKite platform. Use this reference to determine which credentials you need and how to configure them.

What credentials do I need?

The type of credentials depends on which API you want to call:

• Config API (create configurations, projects, applications, policies, knowledge queries) → Use Service Account credentials
• All other APIs (Capture, CIQ execution, AuthZEN evaluation, EntityMatching) → Use AppAgent credentials
• User-context operations (KBAC queries, CIQ with user identity) → Use User Access Token with AppAgent credentials

Service Account Credentials

What are Service Account credentials?

Service Account (SA) credentials authenticate requests to the Config API. They are organization-level credentials used to manage configurations, create projects, and set up applications.

The SA credentials file contains:

• API endpoint URL
• JWK (JSON Web Key) information
• Bearer token for authentication

How do I create Service Account credentials?

Option 1: Via the Hub UI (first time)

1. Go to the IndyKite Hub at the Organization level.
2. Create a new Service Account.
3. Create credentials for the Service Account.
4. Download the credentials JSON file.

Option 2: Via REST API (subsequent credentials)

Endpoint: POST /service-accounts

Option 3: Via Terraform (subsequent credentials)

Plugin: Terraform plugin registry

How do I use Service Account credentials with the REST API?

1. Open your SA credentials file and locate the token field.
2. In your HTTP request, set the Authorization header:

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

Config API Reference: https://openapi.indykite.com/api-documentation-config

How do I use Service Account credentials with Terraform?

Set one of these environment variables:

export INDYKITE_SERVICE_ACCOUNT_CREDENTIALS_FILE=/path/to/credentials.json

Or provide the credentials content directly:

export INDYKITE_SERVICE_ACCOUNT_CREDENTIALS='{"serviceAccountId":"...","endpoint":"..."}'

Terraform Guide: https://developer.indykite.com/guides/guide-terraform

AppAgent Credentials

What are AppAgent credentials?

AppAgent credentials authenticate requests to all IndyKite APIs except the Config API:

• Capture API (store nodes and relationships)
• CIQ execute (read query and update graph data)
• Authorization API (KBAC/AuthZEN policy evaluation)
• EntityMatching API (identity resolution)

AppAgent credentials are project-level credentials tied to a specific Application.

How do I create AppAgent credentials?

You must create resources in this order:

1. Create an Application under your Project.
2. Create an Application Agent under the Application.
3. Create Credentials for the Application Agent.

Methods:

• Hub UI: Navigate to your Project and create through the interface.
• REST API: Environment setup example
• Terraform: Terraform guide

How do I use AppAgent credentials with the REST API?

Current method (API Key):

Set the header:

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

REST API Reference: https://openapi.indykite.com/

What is the _Application node?

When you create an Application with credentials, IndyKite automatically creates an _Application node in your Identity Knowledge Graph (IKG).

You can use this node as an authenticated subject in CIQ queries, allowing your application to act as an identity in the graph.

CIQ Guide: https://developer.indykite.com/guides/guide-contx-iq

User Access Tokens

What is a User Access Token?

A User Access Token is an OAuth 2.0 token issued by an external Authorization Server (identity provider) that represents a user's identity and permissions.

The token contains:

• Claims: Information about the user (email, name, roles).
• Scopes: Permissions granted to the token (read, write, delete).
• Expiration: Time limit for token validity.

When do I need a User Access Token?

Use User Access Tokens when you need to:

• Execute KBAC/AuthZEN authorization queries on behalf of a user.
• Run CIQ queries with user-specific context and permissions.
• Enforce fine-grained access control based on user identity.

How do I use a User Access Token?

Include the token in your HTTP request header:

Authorization: Bearer <user-access-token>

Examples: Developer Hub Resources

How does IndyKite validate User Access Tokens?

IndyKite uses Token Introspection to validate tokens and extract user claims. You must configure a Token Introspect policy that tells IndyKite:

• Which claim to use for matching (e.g., email, sub).
• Which node type to match against in the IKG (e.g., Person).

Token Introspect Guide: https://developer.indykite.com/guides/guide-token-introspect

REST Configuration: POST /token-introspects

API URLs

Which API URL should I use?

Choose the URL based on your data residency requirements:

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

Use the same region as your IndyKite Hub instance.

Security Best Practices

How should I store credentials securely?

• Never commit credentials to version control (Git, GitHub).
• Never expose credentials in client-side code or browser JavaScript.
• Never log credentials or tokens in application logs.

Recommended storage methods:

• Environment variables (for local development).
• Secret management services (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault).
• CI/CD secret storage (GitHub Secrets, GitLab CI Variables).

What should I do if credentials are compromised?

1. Immediately revoke the compromised credentials in the IndyKite Hub.
2. Generate new credentials.
3. Update all applications using the old credentials.
4. Review access logs for unauthorized activity.