From 1a942c51f18dc6441b1afd49bd8697fddc5543fd Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 19 Oct 2026 18:51:43 +0200 Subject: [PATCH 1/8] draft --- app/_indices/ai-gateway.yaml | 1 + app/ai-gateway/access-management.md | 94 +++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 app/ai-gateway/access-management.md diff --git a/app/_indices/ai-gateway.yaml b/app/_indices/ai-gateway.yaml index 1d4753b11dd..8d46052c4d3 100644 --- a/app/_indices/ai-gateway.yaml +++ b/app/_indices/ai-gateway.yaml @@ -125,6 +125,7 @@ sections: - title: Reference items: - path: /ai-gateway/ai-gateway-v2-concepts/ + - path: /ai-gateway/access-management/concepts/ - path: /ai-gateway/configuration/ - path: /ai-gateway/configure-on-prem/ - path: /ai-gateway/v2-migration-guide/ diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md new file mode 100644 index 00000000000..6805b026331 --- /dev/null +++ b/app/ai-gateway/access-management.md @@ -0,0 +1,94 @@ +--- +title: "Access management concepts" +content_type: reference +layout: reference +permalink: /ai-gateway/access-management/concepts/ + +works_on: + - konnect + +products: + - ai-gateway +breadcrumbs: + - /ai-gateway/ +tags: + - ai + - access-control + - authentication + +# TODO: confirm min_version with the Access Management team +min_version: + ai-gateway: '2.2' + +description: "Learn what users, agents, groups, identity providers, Token Vault, and virtual keys are in {{site.ai_gateway}} access management, and how they relate to each other." + +related_resources: + - text: "{{site.ai_gateway}}" + url: /ai-gateway/ + - text: "Principals and directories" + url: /identity/principals/ + - text: "AI Agents" + url: /ai-gateway/entities/ai-agent/ + - text: "AI Vaults" + url: /ai-gateway/entities/ai-vault/ + - text: "AI Consumers" + url: /ai-gateway/entities/ai-consumer/ +--- + +Intro + +## How access management works + + + +## Users + + + +## Agents + + + +## Groups + + + +## Identity Providers + + + +## Token Vault + + + +## Virtual Keys + + From 7142ccb8fe1001142a7c1f6143d15ddb2248e181 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Thu, 22 Oct 2026 11:55:46 +0200 Subject: [PATCH 2/8] draft users --- app/ai-gateway/access-management.md | 100 ++++++++++++++++++---------- 1 file changed, 65 insertions(+), 35 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index 6805b026331..687929f593a 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -35,60 +35,90 @@ related_resources: url: /ai-gateway/entities/ai-consumer/ --- -Intro +Access management allows you to define who can use your organization's resources (like models or MCP servers) in {{site.ai_gateway}}. ## How access management works - +Access management uses Kong Identity features to answer two questions: + +* Who is making the request? +* What are they allowed to do with it? + +You can give specific permissions to users individually or in bulk using [groups](/identity/groups/). + + ## Users - +A user is a person that gets into the system in one of two ways: + +* An admin manually creates them. +* {{site.identity}} creates them automatically the first time they log in through OIDC. + +Once a user exists, an admin can edit their details, add them to or remove them from groups, create virtual keys for them, or delete them. A user can also set their own virtual key. + +You can view all users in one searchable table. Search matches on name only. You can filter the table by team, source, and status, and show or hide columns such as metadata and labels. + +A user can have a cost center, which is a free-form string. {{site.ai_gateway}} doesn't keep a list of cost centers or validate the value. + +For more on how identities are stored, see [Principals and directories](/identity/principals/). ## Agents - + +An agent here is the caller. It's not the same thing as an [AI Agent](/ai-gateway/entities/ai-agent/), which is a {{site.ai_gateway}} entity that agents get called through. + + ## Groups - +A group is a list of users that share the same rules. Instead of setting rules on each member, you set them once on the group. + +Admins create groups by hand. A group can't contain another group. + +In the Konnect UI, you can: + +* View groups in a list. +* Create a group with a name and description. +* Add labels and metadata to a group. +* Add users to a group, either from the groups screen or from a user. +* Edit a group and view its details. +* Delete a group. + +Groups don't have a cost center. ## Identity Providers - +An identity provider is an outside service, such as Okta or Auth0, that signs the tokens people and agents present. Kong trusts the ones you list and uses them to check that those tokens are genuine. + +Token Vault needs at least one trusted identity provider to verify callers. You can add a provider, remove one you no longer want Token Vault to rely on, and review the table of trusted providers with their display names, issuer URLs, and linked identities. + + ## Token Vault - +Token Vault stores credentials so that {{site.ai_gateway}} can call outside services on behalf of a caller. Setting it up involves: + +1. Adding at least one trusted [identity provider](#identity-providers). +1. Generating a public encryption key for the vault and setting the private key reference on a gateway. +1. Creating credential providers. A credential provider uses either OAuth or a static API key. + +When you set up an MCP server, you can choose a credential provider for outbound authentication as an alternative to pass-through. You can view the credentials stored in the vault from the provider and identity provider detail pages. + + ## Virtual Keys - +A virtual key is an API key that lets a caller use {{site.ai_gateway}}. Whoever holds the key is who the gateway treats the caller as. + + + +You can create a key in two ways: + +* Have {{site.ai_gateway}} generate the key. +* Set your own key value. + +In both cases, you set an expiry. When you create a key for someone else, you pick the holder, can filter the holder list by users or agents, and can add a new user or agent inline. + +The key list shows each key's holder, status, expiry, and creation date. You can revoke or delete a key. Rotating a key isn't supported yet. To rotate a key, create a new one and revoke the old one. From 5516b22dc2c5738d1d21634456a7efed1d7a1e54 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Fri, 23 Oct 2026 17:35:41 +0200 Subject: [PATCH 3/8] access management features --- app/ai-gateway/access-management.md | 148 +++++++++++++++++++++------- 1 file changed, 112 insertions(+), 36 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index 687929f593a..246aa79fc1b 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -3,7 +3,6 @@ title: "Access management concepts" content_type: reference layout: reference permalink: /ai-gateway/access-management/concepts/ - works_on: - konnect @@ -25,7 +24,7 @@ description: "Learn what users, agents, groups, identity providers, Token Vault, related_resources: - text: "{{site.ai_gateway}}" url: /ai-gateway/ - - text: "Principals and directories" + - text: "Principals" url: /identity/principals/ - text: "AI Agents" url: /ai-gateway/entities/ai-agent/ @@ -33,51 +32,122 @@ related_resources: url: /ai-gateway/entities/ai-vault/ - text: "AI Consumers" url: /ai-gateway/entities/ai-consumer/ + - text: "Token Vault" + url: /identity/token-vault/ --- -Access management allows you to define who can use your organization's resources (like models or MCP servers) in {{site.ai_gateway}}. +Access management allows you to define who can use your organization's resources, like [models](/ai-gateway/entities/ai-model/) or [MCP servers](/ai-gateway/entities/ai-mcp-server/), in {{site.ai_gateway}}. ## How access management works -Access management uses Kong Identity features to answer two questions: +Access management uses Kong Identity features, such as [principals](/identity/principals/) and [auth servers](/identity/auth-servers/), to answer two questions: * Who is making the request? -* What are they allowed to do with it? - -You can give specific permissions to users individually or in bulk using [groups](/identity/groups/). +* What are they allowed to do? - +You can give permissions to users individually, or in bulk using groups. ## Users -A user is a person that gets into the system in one of two ways: +A user is a person who an admin adds to the system in one of two ways: -* An admin manually creates them. -* {{site.identity}} creates them automatically the first time they log in through OIDC. +* An admin creates them manually, one at a time. +* An admin uploads a CSV file containing the org structure. -Once a user exists, an admin can edit their details, add them to or remove them from groups, create virtual keys for them, or delete them. A user can also set their own virtual key. +To create a user, you must provide the following: -You can view all users in one searchable table. Search matches on name only. You can filter the table by team, source, and status, and show or hide columns such as metadata and labels. +* A name +* An email -A user can have a cost center, which is a free-form string. {{site.ai_gateway}} doesn't keep a list of cost centers or validate the value. +Once a user exists, an admin can: -For more on how identities are stored, see [Principals and directories](/identity/principals/). +* Edit the user's details. +* Add the user to a group, or remove them from one. +* Create or delete [virtual keys](#virtual-keys) for the user. A user can also set their own virtual key. +* Link the user to a cost center. +* Delete or deactivate the user. -## Agents +To stop a user from signing in while keeping their history, deactivate the user instead of deleting them. -An agent is the identity record for a piece of software that calls models or MCP servers. It might act for itself, or on behalf of users. +{:.warning} +> You can't deactivate a user imported from a CSV file. To update the users, import an updated org chart. -An agent here is the caller. It's not the same thing as an [AI Agent](/ai-gateway/entities/ai-agent/), which is a {{site.ai_gateway}} entity that agents get called through. +An admin can view all users in one searchable table. Search matches on name only. You can filter the table by team, source, and status, and show or hide columns such as metadata and labels. - +### Teams + +You can assign users to a team. Teams can't be created manually. They are created when you import an org chart that groups users into teams. Teams can be nested under a parent team. + +## Agents + +An agent is the identity record for a piece of software that calls [models](/ai-gateway/entities/ai-model/) or [MCP servers](/ai-gateway/entities/ai-mcp-server/). It might act for itself, or on behalf of users. + +The agent acts as the caller. Like users, it can: + +* Hold [virtual keys](#virtual-keys) and remote credentials. +* Be linked to a cost center. + +Agents in **Access Management** aren't the same thing as an [AI Agent](/ai-gateway/entities/ai-agent/): + +* **AI Agents** are the resource you call through {{site.ai_gateway}}. +* **Agents** in **Access Management** are the identity that calls {{site.ai_gateway}} resources. + +{:.warning} +> Agents can't belong to teams or sign in through an identity provider. + +## Users versus agents + +Users and agents share the following capabilities: + +* Virtual keys +* Cost center +* Spend limits +* Group membership + +The following table lists their differences: + +{% table %} +columns: + - title: Aspects + key: aspect + - title: Users + key: users + - title: Agents + key: agents +rows: + - aspect: What it represents + users: A person. + agents: Software that calls [models](/ai-gateway/entities/ai-model/), [MCP servers](/ai-gateway/entities/ai-mcp-server/), or other agents, including service accounts such as CI jobs. + - aspect: How it's created + users: Manually, or through an org structure import. + agents: From the **Agents** section. Agents aren't included in org structure imports. + - aspect: Required fields + users: Name and email. + agents: Name. + - aspect: How it authenticates + users: Signs in through an [identity provider](#identity-providers), and calls the gateway with a [virtual key](#virtual-keys). + agents: Uses only the credentials it holds, such as virtual keys and remote credentials. + - aspect: Org structure + users: Can belong to teams, appear on the org chart, and own a team. + agents: Not part of teams or the org chart. + - aspect: Link to a gateway resource + users: Can't be linked to a gateway resource. + agents: Can be linked to the [AI Agent](/ai-gateway/entities/ai-agent/) it represents. + - aspect: Lifecycle + users: Deactivate to stop sign-in and keep history. Imported users can't be deleted, and their name and email are read-only. + agents: Deactivate or delete. + - aspect: Kong Identity API type + users: "`user`" + agents: "`agent`" +{% endtable %} ## Groups A group is a list of users that share the same rules. Instead of setting rules on each member, you set them once on the group. -Admins create groups by hand. A group can't contain another group. +Admins create groups manually. A group can't contain another group. -In the Konnect UI, you can: +In the {{site.konnect_short_name}} UI, you can: * View groups in a list. * Create a group with a name and description. @@ -88,37 +158,43 @@ In the Konnect UI, you can: Groups don't have a cost center. -## Identity Providers +## Identity providers -An identity provider is an outside service, such as Okta or Auth0, that signs the tokens people and agents present. Kong trusts the ones you list and uses them to check that those tokens are genuine. +An identity provider is an external service, such as Okta or Auth0, that signs the tokens people and agents present. Kong trusts the providers you list and uses them to verify that those tokens are genuine. -Token Vault needs at least one trusted identity provider to verify callers. You can add a provider, remove one you no longer want Token Vault to rely on, and review the table of trusted providers with their display names, issuer URLs, and linked identities. +[Token Vault](#token-vault) needs at least one trusted identity provider to verify callers. You can add a provider, remove one you no longer want Token Vault to rely on, and review the table of trusted providers with their display names, issuer URLs, and linked identities. - +To learn more, see [Token Vault's providers](/identity/token-vault/#providers). ## Token Vault -Token Vault stores credentials so that {{site.ai_gateway}} can call outside services on behalf of a caller. Setting it up involves: +Token Vault stores credentials so that {{site.ai_gateway}} can call external services on behalf of a caller. To set it up: + +1. Add at least one trusted [identity provider](#identity-providers). +1. Generate a public encryption key for the vault and set the private key reference on a gateway. +1. Create credential providers. A credential provider uses either OAuth or a static API key. + +When you set up an [MCP server](/ai-gateway/entities/ai-mcp-server/), you can choose a credential provider for outbound authentication as an alternative to pass-through. You can view the credentials stored in the vault from the provider and identity provider detail pages. -1. Adding at least one trusted [identity provider](#identity-providers). -1. Generating a public encryption key for the vault and setting the private key reference on a gateway. -1. Creating credential providers. A credential provider uses either OAuth or a static API key. +To learn more, see [Token Vault](/identity/token-vault/). -When you set up an MCP server, you can choose a credential provider for outbound authentication as an alternative to pass-through. You can view the credentials stored in the vault from the provider and identity provider detail pages. +## Virtual keys - +A virtual key is an API key that lets a caller use {{site.ai_gateway}}. For example, instead of adding an Anthropic API key to an agent, you generate a virtual key for the agent. The agent uses the virtual key, while the provider API keys stay in [Token Vault](#token-vault) instead of in your apps. -## Virtual Keys +Use virtual keys to: -A virtual key is an API key that lets a caller use {{site.ai_gateway}}. Whoever holds the key is who the gateway treats the caller as. +* **Reinforce API key security:** Virtual keys can be generated and revoked cleanly. +* **Enforce and monitor costs:** You can link each virtual key to a cost center and set a spend limit. +* **Gain visibility:** The key list shows when each key was last used, so you can delete stale ones. - +The gateway treats whoever holds the key as the caller. You can create a key in two ways: * Have {{site.ai_gateway}} generate the key. * Set your own key value. -In both cases, you set an expiry. When you create a key for someone else, you pick the holder, can filter the holder list by users or agents, and can add a new user or agent inline. +In both cases, you set an expiry. When you create a key for someone else, you pick the holder. You can filter the holder list by users or agents, and add a new user or agent inline. -The key list shows each key's holder, status, expiry, and creation date. You can revoke or delete a key. Rotating a key isn't supported yet. To rotate a key, create a new one and revoke the old one. +The key list shows each key's holder, status, expiry, and creation date. You can revoke or delete a key. Rotating a key isn't supported. To rotate a key, create a new one and revoke the old one. From 86601452f3093aa4a03c8fb4bdf621fe9898db1d Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 26 Oct 2026 16:34:18 +0100 Subject: [PATCH 4/8] Apply batched suggestions from code review Co-authored-by: Angel Co-authored-by: Julia <101819212+juliamrch@users.noreply.github.com> --- app/ai-gateway/access-management.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index 246aa79fc1b..63ed2a29c2f 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -15,9 +15,8 @@ tags: - access-control - authentication -# TODO: confirm min_version with the Access Management team min_version: - ai-gateway: '2.2' + ai-gateway: '2.3' description: "Learn what users, agents, groups, identity providers, Token Vault, and virtual keys are in {{site.ai_gateway}} access management, and how they relate to each other." @@ -40,7 +39,7 @@ Access management allows you to define who can use your organization's resources ## How access management works -Access management uses Kong Identity features, such as [principals](/identity/principals/) and [auth servers](/identity/auth-servers/), to answer two questions: +Access management features answer two questions: * Who is making the request? * What are they allowed to do? @@ -56,7 +55,7 @@ A user is a person who an admin adds to the system in one of two ways: To create a user, you must provide the following: -* A name +* A name for the user * An email Once a user exists, an admin can: @@ -143,7 +142,7 @@ rows: ## Groups -A group is a list of users that share the same rules. Instead of setting rules on each member, you set them once on the group. +A group is a list of users and agents that share the same rules. Instead of setting rules on each member, you set them once on the group. Admins create groups manually. A group can't contain another group. @@ -155,7 +154,7 @@ In the {{site.konnect_short_name}} UI, you can: * Add users to a group, either from the groups screen or from a user. * Edit a group and view its details. * Delete a group. - +* Export groups as a CSV Groups don't have a cost center. ## Identity providers @@ -171,7 +170,7 @@ To learn more, see [Token Vault's providers](/identity/token-vault/#providers). Token Vault stores credentials so that {{site.ai_gateway}} can call external services on behalf of a caller. To set it up: 1. Add at least one trusted [identity provider](#identity-providers). -1. Generate a public encryption key for the vault and set the private key reference on a gateway. +1. Configure how Token Vault authenticates with this provider 1. Create credential providers. A credential provider uses either OAuth or a static API key. When you set up an [MCP server](/ai-gateway/entities/ai-mcp-server/), you can choose a credential provider for outbound authentication as an alternative to pass-through. You can view the credentials stored in the vault from the provider and identity provider detail pages. @@ -184,7 +183,7 @@ A virtual key is an API key that lets a caller use {{site.ai_gateway}}. For exam Use virtual keys to: -* **Reinforce API key security:** Virtual keys can be generated and revoked cleanly. +* **Reinforce API key security:** Virtual keys can be generated and deleted. * **Enforce and monitor costs:** You can link each virtual key to a cost center and set a spend limit. * **Gain visibility:** The key list shows when each key was last used, so you can delete stale ones. From 015aa1db66513d183a1d7e4ced5831bc74be7b1f Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 26 Oct 2026 16:56:35 +0100 Subject: [PATCH 5/8] update keys and omit unsure info --- app/ai-gateway/access-management.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index 63ed2a29c2f..2791cd8f9d2 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -48,10 +48,11 @@ You can give permissions to users individually, or in bulk using groups. ## Users -A user is a person who an admin adds to the system in one of two ways: +A user is a person who an admin adds to the system in one of three ways: * An admin creates them manually, one at a time. * An admin uploads a CSV file containing the org structure. +* On user sign-in. To create a user, you must provide the following: @@ -71,7 +72,7 @@ To stop a user from signing in while keeping their history, deactivate the user {:.warning} > You can't deactivate a user imported from a CSV file. To update the users, import an updated org chart. -An admin can view all users in one searchable table. Search matches on name only. You can filter the table by team, source, and status, and show or hide columns such as metadata and labels. +An admin can view all users in one searchable table. You can filter the table by team, source, and status, and show or hide columns like metadata and labels. ### Teams @@ -194,6 +195,6 @@ You can create a key in two ways: * Have {{site.ai_gateway}} generate the key. * Set your own key value. -In both cases, you set an expiry. When you create a key for someone else, you pick the holder. You can filter the holder list by users or agents, and add a new user or agent inline. +In both cases, you have the option to set an expiry. When you create a key for someone else, you pick the holder. You can filter the holder list by users or agents, and add a new user or agent inline. -The key list shows each key's holder, status, expiry, and creation date. You can revoke or delete a key. Rotating a key isn't supported. To rotate a key, create a new one and revoke the old one. +The key list shows each key's holder, status, expiry, and creation date. You can delete a keyn but can't rotate it. To rotate a key, create a new one and delete the old one. From fe26600b1c3d8696774fb8e5d3f6151e52335b46 Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 26 Oct 2026 17:19:33 +0100 Subject: [PATCH 6/8] roles and permissions --- app/ai-gateway/access-management.md | 110 +++++++++++++++++++++------- 1 file changed, 85 insertions(+), 25 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index 2791cd8f9d2..b0f3eef5ac3 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -33,6 +33,15 @@ related_resources: url: /ai-gateway/entities/ai-consumer/ - text: "Token Vault" url: /identity/token-vault/ + +faqs: + - q: How can I create a group? + a: | + Admins create groups manually. + + - q: Can a group contain another group? + a: | + No. A group can't contain another group. --- Access management allows you to define who can use your organization's resources, like [models](/ai-gateway/entities/ai-model/) or [MCP servers](/ai-gateway/entities/ai-mcp-server/), in {{site.ai_gateway}}. @@ -48,31 +57,29 @@ You can give permissions to users individually, or in bulk using groups. ## Users -A user is a person who an admin adds to the system in one of three ways: +A user is a person who is added to the system in one of three ways: -* An admin creates them manually, one at a time. +* An admin creates them manually. * An admin uploads a CSV file containing the org structure. -* On user sign-in. +* They sign in for the first time and are created through just-in-time (JIT) provisioning. This requires an [identity provider](#identity-providers) with JIT provisioning enabled. To create a user, you must provide the following: -* A name for the user -* An email +* A user name +* A user email -Once a user exists, an admin can: +To stop a user from signing in while keeping their history, deactivate the user instead of deleting them. -* Edit the user's details. -* Add the user to a group, or remove them from one. -* Create or delete [virtual keys](#virtual-keys) for the user. A user can also set their own virtual key. -* Link the user to a cost center. -* Delete or deactivate the user. +Users imported from an org structure file are managed by that file: -To stop a user from signing in while keeping their history, deactivate the user instead of deleting them. +* You can't delete them. +* Their name and email are read-only. +* If a later import no longer lists them, they are deactivated, not deleted. -{:.warning} -> You can't deactivate a user imported from a CSV file. To update the users, import an updated org chart. +{:.info} +> To change imported users, import an updated org chart. -An admin can view all users in one searchable table. You can filter the table by team, source, and status, and show or hide columns like metadata and labels. +You can view all users in one searchable table. Search matches on name, email, cost center, team, and source. You can filter the table by team, source, and status, and show or hide columns such as metadata and labels. ### Teams @@ -119,7 +126,7 @@ rows: users: A person. agents: Software that calls [models](/ai-gateway/entities/ai-model/), [MCP servers](/ai-gateway/entities/ai-mcp-server/), or other agents, including service accounts such as CI jobs. - aspect: How it's created - users: Manually, or through an org structure import. + users: Manually, through an org structure import, or through JIT provisioning on first sign-in. agents: From the **Agents** section. Agents aren't included in org structure imports. - aspect: Required fields users: Name and email. @@ -145,7 +152,7 @@ rows: A group is a list of users and agents that share the same rules. Instead of setting rules on each member, you set them once on the group. -Admins create groups manually. A group can't contain another group. +Admins create groups manually. A group can't contain another group. Groups don't have a cost center. In the {{site.konnect_short_name}} UI, you can: @@ -155,14 +162,24 @@ In the {{site.konnect_short_name}} UI, you can: * Add users to a group, either from the groups screen or from a user. * Edit a group and view its details. * Delete a group. -* Export groups as a CSV -Groups don't have a cost center. +* Export groups as a CSV. + +### Projects + +A project is a group with its own spend limit. A project can be linked to a cost center, and it holds users and agents only. Projects can't contain other groups. + +You can create a virtual key for a project. Each project key is used by one member of the project, uses the project's access rules and spend limit, and is billed to the project's cost center. ## Identity providers -An identity provider is an external service, such as Okta or Auth0, that signs the tokens people and agents present. Kong trusts the providers you list and uses them to verify that those tokens are genuine. +An identity provider is an external service like Okta or Auth0, that signs the tokens people and agents present. Kong trusts the providers you list and uses them to verify that those tokens are genuine. + +When you add an identity provider, you give it a display name and an issuer URL. You can also: -[Token Vault](#token-vault) needs at least one trusted identity provider to verify callers. You can add a provider, remove one you no longer want Token Vault to rely on, and review the table of trusted providers with their display names, issuer URLs, and linked identities. +* Enable JIT provisioning, so that users are created the first time they sign in. JIT provisioning is separate from Token Vault access. +* Choose whether Token Vault trusts the provider. + +[Token Vault](#token-vault) needs at least one trusted identity provider to verify callers. To learn more, see [Token Vault's providers](/identity/token-vault/#providers). @@ -171,7 +188,7 @@ To learn more, see [Token Vault's providers](/identity/token-vault/#providers). Token Vault stores credentials so that {{site.ai_gateway}} can call external services on behalf of a caller. To set it up: 1. Add at least one trusted [identity provider](#identity-providers). -1. Configure how Token Vault authenticates with this provider +1. Configure how Token Vault authenticates with this provider. 1. Create credential providers. A credential provider uses either OAuth or a static API key. When you set up an [MCP server](/ai-gateway/entities/ai-mcp-server/), you can choose a credential provider for outbound authentication as an alternative to pass-through. You can view the credentials stored in the vault from the provider and identity provider detail pages. @@ -190,11 +207,54 @@ Use virtual keys to: The gateway treats whoever holds the key as the caller. +To create a key, you provide a name and choose a holder: a user, an agent, or a [project](#projects). You can also add a new user or agent inline. + You can create a key in two ways: -* Have {{site.ai_gateway}} generate the key. +* Have {{site.ai_gateway}} generate the key. The key is shown once, after you create it. * Set your own key value. -In both cases, you have the option to set an expiry. When you create a key for someone else, you pick the holder. You can filter the holder list by users or agents, and add a new user or agent inline. +In both cases, you choose an expiry of 30 days, 90 days, 1 year, or never. + +The key list shows each key's name, holder, type, status, expiry, last used date, and creation date. You can filter the list by type and status, and delete one or several keys at once. Rotating a key isn't supported. To rotate a key, create a new one and delete the old one. + +## Roles and permissions + +What you can see and do in access management depends on your role. The following table lists what each role can do. -The key list shows each key's holder, status, expiry, and creation date. You can delete a keyn but can't rotate it. To rotate a key, create a new one and delete the old one. +{% table %} +columns: + - title: Area + key: area + - title: Admin + key: admin + - title: Team manager + key: manager + - title: Individual + key: individual +rows: + - area: Users and org chart + admin: Create, import, edit, deactivate, and delete users. View the org chart. + manager: No access. + individual: No access. + - area: Agents + admin: Create agents directly. + manager: Request an agent. The request is sent to the platform team. + individual: Request an agent. The request is sent to the platform team. + - area: Groups and projects + admin: View all groups and projects. + manager: View the groups and projects they belong to or manage. + individual: View the groups and projects they belong to. + - area: Identity providers + admin: Add, edit, and delete identity providers. + manager: No access. + individual: No access. + - area: Token Vault + admin: Set up and manage Token Vault and its credential providers. + manager: No access. + individual: No access. + - area: Virtual keys + admin: View all keys. Create keys for any holder. + manager: View keys they hold, and keys held by the groups and projects they belong to or manage. + individual: View the keys they hold. +{% endtable %} From 90e243e70e79166817f06709b372998792fa792d Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 26 Oct 2026 17:24:42 +0100 Subject: [PATCH 7/8] update groups section --- app/ai-gateway/access-management.md | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index b0f3eef5ac3..58a8d70c9d0 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -150,19 +150,9 @@ rows: ## Groups -A group is a list of users and agents that share the same rules. Instead of setting rules on each member, you set them once on the group. +A group is a list of users and agents that share the same rules. Instead of setting rules on each member, you set them once on the group. For example, you can select a group when setting up a spend limit in the cost center. -Admins create groups manually. A group can't contain another group. Groups don't have a cost center. - -In the {{site.konnect_short_name}} UI, you can: - -* View groups in a list. -* Create a group with a name and description. -* Add labels and metadata to a group. -* Add users to a group, either from the groups screen or from a user. -* Edit a group and view its details. -* Delete a group. -* Export groups as a CSV. +Admins create groups manually. A group has a name, a description, labels, and metadata. A group can't contain another group, and doesn't have a cost center. ### Projects @@ -242,7 +232,7 @@ rows: manager: Request an agent. The request is sent to the platform team. individual: Request an agent. The request is sent to the platform team. - area: Groups and projects - admin: View all groups and projects. + admin: View all groups and projects. Create, edit, and delete groups and projects. Add or remove members. Export groups as a CSV. manager: View the groups and projects they belong to or manage. individual: View the groups and projects they belong to. - area: Identity providers From 3ec0e6dcdf5baac397061091c2e036df7b80458d Mon Sep 17 00:00:00 2001 From: Julia <101819212+juliamrch@users.noreply.github.com> Date: Mon, 26 Oct 2026 17:29:56 +0100 Subject: [PATCH 8/8] make the idp vs agents section coherent --- app/ai-gateway/access-management.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/app/ai-gateway/access-management.md b/app/ai-gateway/access-management.md index 58a8d70c9d0..6176eb3a82e 100644 --- a/app/ai-gateway/access-management.md +++ b/app/ai-gateway/access-management.md @@ -162,7 +162,9 @@ You can create a virtual key for a project. Each project key is used by one memb ## Identity providers -An identity provider is an external service like Okta or Auth0, that signs the tokens people and agents present. Kong trusts the providers you list and uses them to verify that those tokens are genuine. +An identity provider is an external service, like Okta or Auth0, that signs the tokens users present when they sign in. Kong trusts the providers you list and uses them to verify that those tokens are genuine. + +Only users sign in through an identity provider. Agents can hold credentials and use [Token Vault](#token-vault), but they can't sign in. When you add an identity provider, you give it a display name and an issuer URL. You can also: @@ -175,7 +177,9 @@ To learn more, see [Token Vault's providers](/identity/token-vault/#providers). ## Token Vault -Token Vault stores credentials so that {{site.ai_gateway}} can call external services on behalf of a caller. To set it up: +Token Vault stores credentials so that {{site.ai_gateway}} can call external services on behalf of a caller. When an agent calls on behalf of a user, Token Vault checks that user against a trusted identity provider before releasing credentials. + +To set it up: 1. Add at least one trusted [identity provider](#identity-providers). 1. Configure how Token Vault authenticates with this provider.