{
  "schema_version": 2,
  "id": "operate/iris/intent-router/self-managed/api-examples",
  "title": "Self-managed Intent Router API examples",
  "url": "https://redis.io/docs/latest/operate/iris/intent-router/self-managed/api-examples/",
  "summary": "Create a Router, mint an agent key, verify agent access, hand off to a developer, and rotate or revoke keys.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-10-30T10:17:15-04:00",
  "page_type": "content",
  "content_hash": "8a5c43031efea7f0ca5626a29fe58f0b90b836d62a5890aa05ff50ae8d8308a4",
  "sections": [
    {
      "id": "code-examples",
      "title": "Code examples",
      "role": "example",
      "text": "These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough.\n\n\nAfter you deploy Intent Router, developers still can't use it until a Router and an agent key exist. This page walks through that setup: you create a Router, issue an agent key for it, check that the key works, and give the connection values to a developer. The developer then continues with the [developer quickstart](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart). The page also covers rotating and revoking agent keys after handoff.\n\nBefore you begin, [deploy the chart](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/deploy) and [load the administration tokens](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/authentication#load-the-administration-tokens)."
    },
    {
      "id": "set-connection-values",
      "title": "Set connection values",
      "role": "content",
      "text": "Forward the control plane, the data plane, and the Identity Service in separate terminals, as in [Deploy](https://redis.io/docs/latest/operate/iris/intent-router/self-managed/deploy#5-verify-pods-and-health), then export the connection values:\n\n[code example]\n\n`IRIS_INTENT_ROUTER_SERVICE_TOKEN` holds the admin token and `IRIS_IDENTITY_TOKEN` holds the Identity Service control token. `IRIS_IDENTITY_TENANT` is the deployment's `tenantId`. For application deployment, use the endpoints your platform exposes."
    },
    {
      "id": "create-a-router",
      "title": "Create a Router",
      "role": "content",
      "text": "List the offered models, then create a Router with one of them and wait for it to be ready. See [Manage Routers](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-routers) for each step with Python, TypeScript, and the command-line interface (CLI).\n\n**Available in:** cURL (Iris), CLI (Iris)\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\n**Available in:** cURL (Iris), CLI (Iris)\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\n**Available in:** cURL (Iris), CLI (Iris)\n\n##### cURL (Iris)\n\n[code example]\n\n##### CLI (Iris)\n\n[code example]\n\n\n\nThe create step saves the new Router's ID in `ROUTER_ID`. With the CLI, `iris intent-router service create --wait --write-env .env` creates the Router, waits until it is `READY`, and also mints its agent key into `.env`, so you can skip the next section."
    },
    {
      "id": "mint-an-agent-key",
      "title": "Mint an agent key",
      "role": "content",
      "text": "Issue one key with a `write` grant on the Router. In a new shell, first set `ROUTER_ID` to the saved `routerId`.\n\n[code example]\n\n> [!WARNING]\n> The response holds the key's `token` only once, when you mint or rotate the key. Store it in a secret manager and keep it out of source control.\n\nUse `read` instead of `write` for an application that only classifies queries.\n\nWith the CLI, `iris intent-router service key \"$ROUTER_ID\" --role write --name support-app --write .env` mints the same key and writes the `IRIS_INTENT_ROUTER_*` values to `.env`. It reads `IRIS_IDENTITY_URL`, `IRIS_IDENTITY_TOKEN`, and `IRIS_IDENTITY_TENANT`."
    },
    {
      "id": "verify-agent-access",
      "title": "Verify agent access",
      "role": "content",
      "text": "Check that the key reaches the Router:\n\n[code example]"
    },
    {
      "id": "hand-off-to-a-developer",
      "title": "Hand off to a developer",
      "role": "content",
      "text": "Give the developer the data-plane endpoint as `IRIS_INTENT_ROUTER_URL`, the Router ID as `IRIS_INTENT_ROUTER_ID`, and the agent key as `IRIS_INTENT_ROUTER_API_KEY`. They continue with the [quickstart](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/quickstart). Give platform teams who manage Routers the control-plane URL and admin token for [Manage Routers](https://redis.io/docs/latest/develop/ai/context-engine/intent-router/manage-routers). Remove `agent-key.json` and `agent-grant.json` after you save the token."
    },
    {
      "id": "rotate-or-revoke-agent-keys",
      "title": "Rotate or revoke agent keys",
      "role": "content",
      "text": "Rotating a key mints a replacement with a new `keyId` and token. The old key keeps working for a grace period, 3,600 seconds by default, so applications can switch over. Set `graceSeconds` to change it. Rotation returns the new token once:\n\n[code example]\n\nWith the CLI, run `iris identity keys rotate \"$KEY_ID\" --grace 10m --write .env --env IRIS_INTENT_ROUTER_API_KEY`.\n\nRevoke a key to stop it working:\n\n[code example]\n\nWith the CLI, run `iris identity keys revoke \"$KEY_ID\"`. `iris identity keys list --resource-id \"$ROUTER_ID\"` lists a Router's keys.\n\nA revoked key stops working within 300 seconds, the Identity Service's default cache lifetime. Revoke the keys for a Router before you delete it."
    }
  ],
  "examples": [
    {
      "id": "set-connection-values-ex0",
      "language": "bash",
      "code": "export IRIS_INTENT_ROUTER_SERVICE_URL='http://localhost:9400'\nexport IRIS_INTENT_ROUTER_URL='http://localhost:9401'\nexport IRIS_IDENTITY_URL='http://localhost:9200'\nexport IRIS_IDENTITY_TENANT='<tenant-id>'\numask 077",
      "section_id": "set-connection-values"
    },
    {
      "id": "create-a-router-ex0",
      "language": "bash",
      "code": "SERVICE_API=\"${IRIS_INTENT_ROUTER_SERVICE_URL%/}/iris/v1/intent\"\ncurl --fail-with-body --silent --show-error \\\n  \"$SERVICE_API/models?purpose=EMBEDDING\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_SERVICE_TOKEN\" > models.json\njq -c '.items[] | {provider, model, dimensions, authorization}' models.json",
      "section_id": "create-a-router"
    },
    {
      "id": "create-a-router-ex1",
      "language": "bash",
      "code": "iris --json intent-router service models --purpose embedding > models.json\njq -c '.items[] | {provider, model, dimensions, authorization}' models.json",
      "section_id": "create-a-router"
    },
    {
      "id": "create-a-router-ex2",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  -X POST \"$SERVICE_API/routers\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_SERVICE_TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  --data \"$(jq '{\n    name: \"support-router\",\n    description: \"Routes support requests to tools and agents.\",\n    template: \"AGENT\",\n    minScore: 0.7,\n    vectorSpace: (.items[0] | {provider, model, dimensions})\n  }' models.json)\" > router.json\nROUTER_ID=$(jq -er .routerId router.json)\njq -c '{routerId, state, revision}' router.json",
      "section_id": "create-a-router"
    },
    {
      "id": "create-a-router-ex3",
      "language": "bash",
      "code": "iris intent-router service create --name support-router \\\n  --description \"Routes support requests to tools and agents.\" \\\n  --template agent --min-score 0.7 \\\n  --provider \"$(jq -er '.items[0].provider' models.json)\" \\\n  --model \"$(jq -er '.items[0].model' models.json)\" \\\n  --dimensions \"$(jq -er '.items[0].dimensions' models.json)\" \\\n  --wait | tee router.env\nROUTER_ID=$(sed -n 's/^IRIS_INTENT_ROUTER_ID=//p' router.env)",
      "section_id": "create-a-router"
    },
    {
      "id": "create-a-router-ex4",
      "language": "bash",
      "code": "until [ \"$(curl --fail-with-body --silent --show-error \\\n  \"$SERVICE_API/routers/$ROUTER_ID\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_SERVICE_TOKEN\" | tee router.json | jq -r .state)\" != \"PROVISIONING\" ]; do\n  sleep 1\ndone\njq -c '{routerId, state, failureReason}' router.json\njq -e '.state == \"READY\"' router.json > /dev/null",
      "section_id": "create-a-router"
    },
    {
      "id": "create-a-router-ex5",
      "language": "bash",
      "code": "iris --json intent-router service show \"$ROUTER_ID\" > router.json\njq -c '{routerId, state, failureReason}' router.json\njq -e '.state == \"READY\"' router.json > /dev/null",
      "section_id": "create-a-router"
    },
    {
      "id": "mint-an-agent-key-ex0",
      "language": "bash",
      "code": ": \"${ROUTER_ID:?Set ROUTER_ID to the saved routerId}\"\njq -n --arg tenant \"$IRIS_IDENTITY_TENANT\" --arg router \"$ROUTER_ID\" '{\n  name: \"support-app\",\n  grants: [\n    {tenant: $tenant, product: \"intent\", resourceType: \"intent-router\", resourceId: $router, actions: [\"write\"]}\n  ]\n}' > agent-grant.json\n\ncurl --fail-with-body --silent --show-error \\\n  -X POST \"$IRIS_IDENTITY_URL/v1/api-keys\" \\\n  -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  --data-binary @agent-grant.json > agent-key.json\n\nexport IRIS_INTENT_ROUTER_ID=\"$ROUTER_ID\"\nexport IRIS_INTENT_ROUTER_API_KEY=\"$(jq -er '.token' agent-key.json)\"\nKEY_ID=\"$(jq -er '.keyId' agent-key.json)\"\njq '{keyId, createdAt}' agent-key.json",
      "section_id": "mint-an-agent-key"
    },
    {
      "id": "verify-agent-access-ex0",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  \"$IRIS_INTENT_ROUTER_URL/iris/data/v1/intent/routers/$IRIS_INTENT_ROUTER_ID/health\" \\\n  -H \"Authorization: Bearer $IRIS_INTENT_ROUTER_API_KEY\" | jq .",
      "section_id": "verify-agent-access"
    },
    {
      "id": "rotate-or-revoke-agent-keys-ex0",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  -X POST \"$IRIS_IDENTITY_URL/v1/api-keys/$KEY_ID/rotate?graceSeconds=600\" \\\n  -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\" > agent-key.json\nexport IRIS_INTENT_ROUTER_API_KEY=\"$(jq -er '.token' agent-key.json)\"\nKEY_ID=\"$(jq -er '.keyId' agent-key.json)\"\njq '{keyId, createdAt, oldExpiresAt}' agent-key.json",
      "section_id": "rotate-or-revoke-agent-keys"
    },
    {
      "id": "rotate-or-revoke-agent-keys-ex1",
      "language": "bash",
      "code": "curl --fail-with-body --silent --show-error \\\n  -X DELETE \"$IRIS_IDENTITY_URL/v1/api-keys/$KEY_ID\" \\\n  -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\"",
      "section_id": "rotate-or-revoke-agent-keys"
    }
  ]
}