Agent and API Provider Management

Note for Tyk Cloud UsersThis documentation is for users who run their self-managed agents. If you’re using Tyk Cloud, agents are automatically managed for your Tyk Dashboard, and you don’t need to worry about installation, access tokens, or configuration. You can use the “Agents” and “API Provider” pages in the Tyk Cloud dashboard to check connection health between the agents and Governance Hub.

Availability

Version: Available since v0.2

Overview

Agent and API Provider Management enables you to deploy, configure, and monitor the Tyk Governance agents that discover and synchronize APIs from various providers.

Understanding Agents and API Providers

Agents are lightweight services that act as secure bridges between your API providers and the Tyk Governance Hub. They:

Run in your environment (on-premises, cloud, or hybrid)
Connect to one or more API providers to discover APIs
Securely transmit API data to the Governance Hub
Support high availability deployments
Can be monitored through the “Agents” section in the UI

API Providers are the systems where your APIs are defined and managed, such as:

Tyk Dashboard
AWS API Gateway

Each provider is configured within an agent and can be monitored through the “API Providers” section in the UI, where you can see:

How many APIs are discovered from each provider
The connection status of each provider
The last synchronization time
Provider-specific details

Key Benefits

Centralized Agent Visibility: Monitor all agents from a single dashboard
Scheduled Synchronization: Configure automatic API discovery at regular intervals
High Availability Deployment: Deploy multiple agent replicas with automatic leader election
Detailed Status Monitoring: Track agent health, connection status, and synchronization history
Secure Communication: All agent-to-hub communication is encrypted and authenticated

Dependencies

Requires Tyk Governance and agents v0.2 or higher
Agents support Kubernetes-based high availability, which requires Kubernetes cluster access

Quick Start

In this tutorial, we’ll set up a new agent, configure it to connect to an API provider, and monitor its status.

Prerequisites

Access to Tyk Governance Hub
Access to an API provider (Tyk Dashboard or AWS API Gateway)
A server or container environment to run the agent

Step-by-Step

Create a New Agent

From the Agents page, click the New agent button in the top-right corner.
In the New agent form, enter:
- Name: A descriptive name for the agent (required)
- Description: Details about the agent’s purpose or location (required)
Click Create agent to save the new agent.

Alternatively, use the API to create a new agent:

# Replace with your actual Governance URL and API key
GOVERNANCE_URL="https://your-governance-instance.tyk.io"
API_KEY="your-access-key"
AGENT_NAME="My API Provider Agent"

# Create agent
curl -s -X POST "${GOVERNANCE_URL}/api/agents/" \
    -H "X-API-Key: ${API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "'"${AGENT_NAME}"'"
    }'

Note the agent ID returned in the response:

{"id":"a51d9bd0-bafe-4749-8285-e18641b151f2","name":"My API Provider Agent","last_heartbeat":"0001-01-01T00:00:00Z","status":"INACTIVE","providers":null}

Generate an Agent Token
- In the Agent information section, find the Access token field.
- If no token exists, click Generate new access token.
- For existing tokens:
  - Click the eye icon to show/hide the token
  - Use the copy icon to copy the token to your clipboard
  - Use this token in your agent configuration file
- Alternatively, generate an authentication token for the agent using the API:
  # Replace with the agent ID from the previous step AGENT_ID="a51d9bd0-bafe-4749-8285-e18641b151f2" # Generate token curl -X POST "${GOVERNANCE_URL}/api/auth/token/" \ -H "X-API-Key: ${API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "'"${AGENT_ID}"'" }'
  Save the token from the response:
  { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

Create Agent Configuration File Create a file named agent-config.yaml with the following content:

# Tyk Governance Agent Configuration
governanceDashboard:
    server:
        # The gRPC endpoint URL of the Tyk Governance service
        url: "your-governance-instance.tyk.io:50051"
    
    auth:
        # Authentication token for this agent
        token: "your-agent-token"

# API Provider Configurations
instances:
    # Example Tyk Provider Configuration
    - name: "tyk-provider"
    type: "tyk"
    config:
        host: "http://your-tyk-dashboard:3000"
        auth: "your-tyk-dashboard-api-key"
    
    # Example AWS API Gateway Configuration
    - name: "aws-provider"
    type: "aws"
    config:
        accessKeyId: "your-aws-access-key-id"
        accessKeySecret: "your-aws-access-key-secret"
        region: "us-east-1"

Deploy the Agent Run the agent using Docker or as a Kubernetes Deployment. See Installation for details.

Monitor Agent Status

Check the agent status in the Governance Hub. A healthy agent will appear as “Healthy”:

Check the agent status in the Governance Hub using API:

curl "${GOVERNANCE_URL}/api/agents/${AGENT_ID}" \
    -H "X-API-Key: ${API_KEY}"

A healthy agent will show:

{
    "id": "a51d9bd0-bafe-4749-8285-e18641b151f2",
    "name": "My API Provider Agent",
    "last_heartbeat": "2025-07-16T12:34:56Z",
    "status": "ACTIVE",
    "providers": [
        {
            "name": "tyk-provider",
            "type": "tyk"
        },
        {
            "name": "aws-provider",
            "type": "aws"
        }
    ]
}

Trigger Initial Synchronization Trigger a synchronization to verify the agent is working correctly.

Validation

The agent should appear as “Healthy” or have status as “ACTIVE” in the agent list
The agent’s last heartbeat timestamp should be recent
After synchronization, APIs from your providers should appear in the API Repository

How It Works

Agent Management works through a distributed architecture where agents deployed in your environments connect to the central Governance Hub using secure gRPC streams.

Agent Architecture

The agent establishes two persistent gRPC streams with the Governance Hub:

Health Stream: Sends regular heartbeats to indicate the agent is alive and functioning
Sync Stream: Used for API synchronization operations

When multiple agent replicas are deployed with leader election enabled, they use Kubernetes leader election to ensure only one instance actively performs synchronization, while others stand by as hot backups.

Synchronization Process

Synchronization can be triggered in three ways:

Manual Trigger: Through the Governance Hub UI or API
Scheduled Sync: At regular intervals configured in the agent. See Understanding Scheduled Synchronization.
Initial Connection: When an agent first connects to the Governance Hub

Understanding Scheduled Synchronization

You can configure scheduled synchronization for each API provider using the Governance Hub API (Hub-side scheduling). Use the /api/agents/{id}/sync-jobs endpoint to configure provider-specific schedules:

# Schedule sync for a specific provider
curl -X POST "${GOVERNANCE_URL}/api/agents/${AGENT_ID}/sync-jobs" \
   -H "X-API-Key: ${API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
        "repeat_every": "12h",
        "provider": "tyk-provider",
        "start_from": "2023-06-01T12:00:00Z"
   }'

With this approach:

The Governance Hub’s scheduler component manages the schedule
The Hub initiates synchronization by sending requests to the agent
It’s a “push” model where the Hub tells the agent when to sync
You can set different schedules for different providers
Supports Go duration format (e.g., “1h”, “12h”, “7d”)

During synchronization:

The agent receives a sync request from the hub (or initiates it based on its schedule)
The agent queries each configured API provider for APIs
The agent processes and normalizes the API definitions
The agent streams the API definitions to the hub
The hub processes and stores the API definitions
The hub reconciles the API inventory, marking missing APIs as deleted

Deployment Scenarios

Multi-Provider API Discovery

Deploy agents to connect to different API providers across your organization, creating a comprehensive API inventory that spans platforms.

# Agent configuration with multiple providers
instances:
  - name: "tyk-dashboard"
    type: "tyk"
    config:
      host: "http://tyk-dashboard:3000"
      auth: "your-tyk-api-key"
  
  - name: "aws-us-east"
    type: "aws"
    config:
      accessKeyId: "your-aws-access-key"
      accessKeySecret: "your-aws-secret-key"
      region: "us-east-1"
  
  - name: "aws-eu-west"
    type: "aws"
    config:
      accessKeyId: "your-aws-access-key"
      accessKeySecret: "your-aws-secret-key"
      region: "eu-west-1"

High Availability Agent Deployment

Deploy multiple agent replicas in Kubernetes to ensure continuous API discovery even if some instances fail.

# Kubernetes deployment with leader election
apiVersion: apps/v1
kind: Deployment
metadata:
  name: governance-agent
spec:
  replicas: 3  # Multiple replicas for redundancy
  template:
    spec:
      containers:
      - name: agent
        env:
        - name: POD_NAME # When leader election is enabled, POD_NAME environment variables must be set
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE # When leader election is enabled, POD_NAMESPACE environment variables must be set
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: TYK_AGENT_LEADERELECTION_ENABLED
          value: "true"

Configuration Options

Agent Configuration File

The agent is configured using a YAML configuration file with the following sections:

Core Configuration

# Governance Dashboard Connection
governanceDashboard:
  server:
    url: "your-governance-instance.tyk.io:50051"
  auth:
    token: "your-agent-token"

# Log level (debug, info, warn, error)
logLevel: info

# Health probe configuration
healthProbe:
  server:
    port: 5959

API Provider Configuration

# API Provider Configurations
instances:
  # Tyk Provider
  - name: "tyk-provider"
    type: "tyk"
    config:
      host: "http://dashboard:3000"
      auth: "your-tyk-api-key"
  
  # AWS API Gateway Provider
  - name: "aws-provider"
    type: "aws"
    config:
      accessKeyId: "your-aws-access-key-id"
      accessKeySecret: "your-aws-access-key-secret"
      region: "us-east-1"
      # Optional session token for temporary credentials
      sessionToken: "your-aws-session-token"

gRPC Connection (New in v0.2)

rpc:
  # Keepalive configures the keepalive settings for the gRPC connection.
  keepalive:
    # Enabled controls whether keepalive is enabled.
    enabled: true
    # Time is the duration after which if there are no activities, ping will be sent.
    time: 30s
    # Timeout is the duration the client waits for a response to a keepalive ping.
    timeout: 20s
    # PermitWithoutStream if true allows sending pings even without active streams.
    permitWithoutStream: true

High Availability Configuration (New in v0.2)

leaderElection:
  # Enable or disable leader election
  enabled: true
  # Name of the Kubernetes lease object used for leader election
  leaseName: "governance-agent-lock"
  # Namespace where the lease object will be created
  # If not specified, the agent's namespace will be used
  leaseNamespace: ""
  # Duration that non-leader candidates will wait before attempting to acquire leadership
  leaseDuration: "15s"
  # Duration that the acting leader will retry refreshing leadership before giving up
  renewDeadline: "10s"
  # Duration the leader elector clients should wait between leadership acquisition attempts
  retryPeriod: "2s"

Environment Variables

The agent supports configuration through environment variables:

Environment Variable	Description	Default Value
`TYK_AGENT_LICENSEKEY`	Your Tyk Governance license key	-
`TYK_AGENT_LOGLEVEL`	Log level (debug, info, warn, error)	`info`
`TYK_AGENT_GOVERNANCEDASHBOARD_SERVER_URL`	The gRPC endpoint URL of the Tyk Governance service	-
`TYK_AGENT_GOVERNANCEDASHBOARD_SERVER_TLS_ENABLED`	Enable TLS for gRPC connections	`false`
`TYK_AGENT_GOVERNANCEDASHBOARD_SERVER_TLS_CACERTPATH`	Path to CA certificate	-
`TYK_AGENT_GOVERNANCEDASHBOARD_SERVER_TLS_CLIENTCERTPATH`	Path to client certificate (for mTLS)	-
`TYK_AGENT_GOVERNANCEDASHBOARD_SERVER_TLS_CLIENTKEYPATH`	Path to client key (for mTLS)	-
`TYK_AGENT_GOVERNANCEDASHBOARD_SERVER_TLS_INSECURESKIPVERIFY`	Skip verification of server certificate	`false`
`TYK_AGENT_GOVERNANCEDASHBOARD_AUTH_TOKEN`	Authentication token for the agent	-
`TYK_AGENT_HEALTHPROBE_SERVER_PORT`	Port for health probe server	`5959`

gRPC Connection Variables (New in v0.2)

Environment Variable	Description	Default Value
`TYK_AGENT_RPC_KEEPALIVE_ENABLED`	Enables/disables keepalive	`true`
`TYK_AGENT_RPC_KEEPALIVE_TIME`	Duration after which ping is sent	`30s`
`TYK_AGENT_RPC_KEEPALIVE_TIMEOUT`	Duration client waits for ping response from the server	`20s`
`TYK_AGENT_RPC_KEEPALIVE_PERMITWITHOUTSTREAM`	Allows sending pings without active streams	`true`

Leader Election Variables (New in v0.2)

Environment Variable	Description	Default Value
`TYK_AGENT_LEADERELECTION_ENABLED`	Enable Kubernetes leader election	`false`
`TYK_AGENT_LEADERELECTION_LEASENAME`	Name of the lease object	`governance-agent-lock`
`TYK_AGENT_LEADERELECTION_LEASENAMESPACE`	Namespace for the lease object	Agent’s namespace
`TYK_AGENT_LEADERELECTION_LEASEDURATION`	Duration for lease	`15s`
`TYK_AGENT_LEADERELECTION_RENEWDEADLINE`	Deadline for renewing leadership	`10s`
`TYK_AGENT_LEADERELECTION_RETRYPERIOD`	Period between retry attempts	`2s`

Required Environment Variables for Leader Election

When leader election is enabled, the following environment variables must also be set:

POD_NAME: The name of the pod (used as the identity for leader election)
POD_NAMESPACE: The namespace of the pod (used for creating the lease object)

These are typically set automatically when deploying with Kubernetes using the downward API:

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: POD_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace

Use Cases

Multi-Region API Discovery

For organizations with APIs deployed across multiple geographic regions, deploy region-specific agents to efficiently discover and monitor APIs while respecting network boundaries. Implementation:

Deploy agents in each region where APIs are hosted
Configure each agent with the appropriate regional API providers
Use descriptive names to identify regional agents
Monitor all agents from the central Governance Hub

Benefits:

Reduced latency for API discovery operations
Respect for network boundaries and security zones
Improved reliability with region-specific agents
Clear organization of APIs by region

Secure Environment Bridging

For organizations with strict network segmentation, use agents to securely bridge between isolated environments without compromising security boundaries. Implementation:

Deploy agents in each network segment
Configure outbound-only connections from agents to the Governance Hub
Use separate agents for production and non-production environments
Implement appropriate network security controls around agent traffic

Benefits:

Maintain network isolation while enabling governance
No inbound connections required to sensitive environments
Granular control over which APIs are discovered
Separation of concerns between environments

Automated API Lifecycle Tracking

Use scheduled synchronization to automatically track the lifecycle of APIs, including when they’re created, updated, or deleted from source providers. Implementation:

Configure agents with scheduled synchronization
Set appropriate sync intervals based on change frequency
Use the API Repository to monitor API status
Create reports showing API lifecycle events

Benefits:

Automatic detection of API changes
Historical record of API lifecycle events
Reduced manual tracking effort
Improved visibility into API landscape evolution

Best Practices and Recommendations

Use descriptive agent names that indicate their purpose and scope
Deploy agents close to API providers to minimize latency and network issues
Configure appropriate sync intervals based on how frequently your APIs change
Use leader election for high availability when deploying multiple agent replicas
Monitor agent health regularly to ensure continuous API discovery
Rotate API provider credentials periodically for better security
Use the principle of least privilege when configuring API provider credentials
Start with manual syncs before enabling scheduled synchronization
Implement network security controls around agent traffic
Maintain agent versions to ensure compatibility with the Governance Hub

FAQs

How many agents do I need?

What happens if an agent goes offline?

How secure is the agent-to-hub communication?

What permissions do agents need for API providers?

Troubleshooting

Agent shows as "INACTIVE"

Agent connects but no APIs are discovered

Multiple agents running when using leader election

Scheduled sync not working

General

​Availability

​Overview

​Understanding Agents and API Providers

​Key Benefits

​Dependencies

​Quick Start

​Prerequisites

​Step-by-Step

​Validation

​How It Works

​Agent Architecture

​Synchronization Process

​Understanding Scheduled Synchronization

​Deployment Scenarios

​Multi-Provider API Discovery

​High Availability Agent Deployment

​Configuration Options

​Agent Configuration File

​Core Configuration

​API Provider Configuration

​gRPC Connection (New in v0.2)

​High Availability Configuration (New in v0.2)

​Environment Variables

​gRPC Connection Variables (New in v0.2)

​Leader Election Variables (New in v0.2)

​Required Environment Variables for Leader Election

​Use Cases

​Multi-Region API Discovery

​Secure Environment Bridging

​Automated API Lifecycle Tracking

​Best Practices and Recommendations

​FAQs

​Troubleshooting

Availability

Overview

Understanding Agents and API Providers

Key Benefits

Dependencies

Quick Start

Prerequisites

Step-by-Step

Validation

How It Works

Agent Architecture

Synchronization Process

Understanding Scheduled Synchronization

Deployment Scenarios

Multi-Provider API Discovery

High Availability Agent Deployment

Configuration Options

Agent Configuration File

Core Configuration

API Provider Configuration

gRPC Connection (New in v0.2)

High Availability Configuration (New in v0.2)

Environment Variables

gRPC Connection Variables (New in v0.2)

Leader Election Variables (New in v0.2)

Required Environment Variables for Leader Election

Use Cases

Multi-Region API Discovery

Secure Environment Bridging

Automated API Lifecycle Tracking

Best Practices and Recommendations

FAQs

Troubleshooting