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, policy listing, Data Schema, 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:

• serviceAccountId: the Service Account GID
• endpoint: the API host for your region, for example eu.api.indykite.com
• privateKeyJWK, privateKeyPKCS8, privateKeyPKCS8Base64: the credential's private key in JWK and PEM form
• token: a ready-to-use Bearer token, present only when the credential was created with an expire_time at most two years ahead (see below)

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-account-credentials with service_account_id (required), and optionally display_name (2-254 characters) and expire_time (RFC 3339). The 201 response carries the credential's id, kid, expire_time and the credentials file itself in service_account_config. Without expire_time the credential never expires and the file has no token. (POST /service-accounts creates the Service Account, not its credentials.)

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>

The token field exists only when the credential expires within two years of its creation. A credential created without expire_time never expires, so its file carries the private key but no token, and you sign a JWT yourself: use privateKeyJWK with its own alg and kid, set iss and sub to the serviceAccountId value (or appAgentId for an Application Agent), and set exp; iat and a unique jti are recommended. The IndyKite SDKs do this for you. A token without iss, sub or exp, or signed with a key the platform does not know, is rejected with 401 and Invalid ServiceAccount JWT in Authorization header (Invalid AppAgent JWT in X-IK-ClientKey header for an Application Agent).

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 and whoami (read query, update graph data, resolve the end-user token's subject)
• Authorization API (KBAC/AuthZEN policy evaluation and search)
• Policy listing (GET /access/v1/policies, the project's active KBAC policies)
• Data Schema API (the observed schema of the IKG)
• EntityMatching API (identity resolution)

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

Each of these APIs is gated by an API permission granted on the Application Agent (api_permissions): Audit, Authorization, Capture, ContXIQ, EntityMatching, ReadAuthZConfigs, and ReadDataSchema. A call to an API the agent is not granted fails with 401 and the message insufficient API access level for appAgent. See the Environment guide for the permission-to-endpoint mapping.

When a credential cannot be checked at all

A 401 means the request was judged and refused: the credential is missing, malformed, expired, revoked, or lacks the API permission, or the call is one the platform does not serve for it (failed to evaluate API access for appAgent for a path no API permission covers, cross region connection not allowed for sandbox for a sandbox credential used in the other region). When the platform cannot reach a verdict on the credential, it does not answer 401, so a client never chases new credentials that would not help:

• 503 Service Unavailable with {"message": "Unable to verify the AppAgent credential token, retry the request"} (or ServiceAccount for a Bearer token): a transient failure while checking the credential. Retry the same request with the same credential, with backoff.
• 500 Internal Server Error with {"message": "Unable to verify the AppAgent credential token"} (or ServiceAccount): the check failed for a non-transient reason. The credential was not judged, so do not rotate it; report the request's trace to IndyKite support.

This applies uniformly to every REST API that takes X-IK-ClientKey or a Service Account Authorization: Bearer header: Config, Capture, AuthZEN, ContX IQ, Entity Matching, and Data Schema.

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>

The AppAgent credentials file has the same shape as the Service Account one, with appAgentId, applicationId and appSpaceId in place of serviceAccountId. The same rule applies to its token: present only for a credential that expires within two years, otherwise sign the JWT yourself as described above with iss and sub set to appAgentId.

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.