Retrieve AgentID Credentials for an Externally-Hosted Agent
An Externally-Hosted agent runs outside WSO2 Agent Manager, so the platform has no pod to inject its AgentID credential into. Instead, you generate the credential from the console and configure your agent with it yourself. This guide walks through generating, using, and rotating that credential.
Prerequisites​
- An Externally-Hosted agent, registered in a project.
- Console access with permission to update the agent.
Unlike Platform-Hosted agents, an Externally-Hosted agent has no deploy or promote step: AgentID provisioning starts for every environment in your organization as soon as the agent is created.
Step 1: Open the Agent's Overview Page​
Navigate to Projects → <your project> → Agents → <your agent>. Each environment appears as its own card, with an Agent Identity section showing the status of that environment's AgentID:
- Provisioning in progress: the identity is still being created. This clears on its own within a few minutes; no action is needed.
- Provisioning failed: check the identity settings for details, or re-open this page later; provisioning retries automatically for a while before giving up.
- A Client ID: provisioning has completed. This is the only value visible by default; the console never displays a secret unless you explicitly ask for one.
Step 2: Generate the Secret​
Once the Client ID is showing, click Generate Secret in the environment card's header. The
new client_id/client_secret pair appears immediately in a warning banner on that card.
Copy both values now. The banner is your only chance to see this secret; Agent Manager never stores it anywhere: the environment's ThunderID instance mints it fresh for this one response, and there is nothing left to retrieve afterward. If you navigate away before copying it, generate a new one; the old one still works until you do.
Step 3: Configure Your Agent​
Set the values from Step 2 as configuration or environment variables for your externally-hosted agent process, in whatever form your deployment uses:
clientIdandclientSecretfrom Step 2.- A token endpoint of
<environment ThunderID base URL>/oauth2/token. You can find the environment's base URL from its ThunderID console URL. - The scopes your agent should request, as documented in your organization's AgentID policy.
From there, your agent mints and uses tokens exactly the same way a Platform-Hosted agent does:
request a token with the client_credentials grant, cache it, and attach it as a bearer token
on calls to the gateway. See
Step 2 and Step 3 of the Platform-Hosted guide
for the exact request shape and a caching example.
Rotating the Credential​
If you need a new secret, for example because the old one may have leaked, click Generate Secret again. This works at any time, not just the first time, and it immediately invalidates the previous secret and shows you the new pair the same way as Step 2.
Update your agent's configuration with the new secret and restart it. Tokens minted with the old secret before the rotation remain valid until they expire, since Thunder cannot invalidate a token it has already issued.
Troubleshooting​
| Symptom | Likely cause |
|---|---|
| The environment card shows "Provisioning in progress" for a long time | Provisioning retries automatically for a while before failing. If it does not clear within about fifteen minutes, check the identity settings for an error. |
| Generate Secret fails | The agent's identity has not finished provisioning for this environment yet, or provisioning failed. Wait for the status to show a Client ID, or check the identity settings for details. |
Token request fails with invalid_client | The clientId/clientSecret pair in your agent's configuration is stale, most likely because someone generated a new one afterward. Generate a fresh pair and update your agent's configuration. |