fix(fetch): add --identity-name option for custom credential lookup

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }
 

src/cli/commands/fetch/__tests__/fetch-access.test.ts

@@ -173,4 +173,24 @@ describe('registerFetch', () => {
  const renderArg = mockRender.mock.calls[0]![0];
  expect(JSON.stringify(renderArg)).toContain('Token fetch failed');
  });
+
+ it('accepts --identity-name option and passes it through to fetchGatewayToken', async () => {
+ mockFetchGatewayToken.mockResolvedValue(jwtResult);
+
+ await program.parseAsync(
+ ['fetch', 'access', '--name', 'myGateway', '--identity-name', 'my-custom-cred', '--json'],
+ {
+ from: 'user',
+ }
+ );
+
+ expect(mockFetchGatewayToken).toHaveBeenCalledWith(
+ 'myGateway',
+ expect.objectContaining({ identityName: 'my-custom-cred' })
+ );
+
+ expect(mockLog).toHaveBeenCalledTimes(1);
+ const output = JSON.parse(mockLog.mock.calls[0][0]);
+ expect(output.success).toBe(true);
+ });
 });

src/cli/commands/fetch/action.ts

@@ -32,7 +32,10 @@ async function handleFetchGatewayAccess(options: FetchAccessOptions): Promise<Fe
  };
  }
 
- const result = await fetchGatewayToken(options.name, { deployTarget: options.target });
+ const result = await fetchGatewayToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  return { success: true, result };
 }
 
@@ -43,7 +46,10 @@ async function handleFetchAgentAccess(options: FetchAccessOptions): Promise<Fetc
 
  let tokenResult: OAuthTokenResult;
  try {
- tokenResult = await fetchRuntimeToken(options.name, { deployTarget: options.target });
+ tokenResult = await fetchRuntimeToken(options.name, {
+ deployTarget: options.target,
+ identityName: options.identityName,
+ });
  } catch (err) {
  return { success: false, error: err instanceof Error ? err.message : String(err) };
  }

src/cli/commands/fetch/command.tsx

@@ -16,6 +16,7 @@
  .option('--name <resource>', 'Gateway or agent name [non-interactive]')
  .option('--type <type>', 'Resource type: gateway (default) or agent [non-interactive]', 'gateway')
  .option('--target <target>', 'Deployment target [non-interactive]')
+ .option('--identity-name <name>', 'Identity credential name for token fetch [non-interactive]')
  .option('--json', 'Output as JSON [non-interactive]')
  .action(async (cliOptions: Record<string, unknown>) => {
  const options = cliOptions as unknown as FetchAccessOptions;
@@ -26,7 +27,7 @@
  result = await handleFetchAccess(options);
  } catch (error) {
  if (options.json) {
  console.log(JSON.stringify({ success: false, error: getErrorMessage(error) }));
  } else {
  render(<Text color="red">Error: {getErrorMessage(error)}</Text>);
  }
@@ -37,11 +38,11 @@
  if (!result.success) {
  if (options.json) {
  console.log(
  JSON.stringify({
  success: false,
  error: result.error,
  ...(result.availableGateways && { availableGateways: result.availableGateways }),
  })
  );
  } else if (!result.availableGateways) {
  render(<Text color="red">{result.error}</Text>);

src/cli/commands/fetch/types.ts

@@ -4,5 +4,6 @@ export interface FetchAccessOptions {
  name?: string;
  type?: FetchResourceType;
  target?: string;
+ identityName?: string;
  json?: boolean;
 }

src/cli/operations/fetch-access/__tests__/fetch-gateway-token.test.ts

@@ -367,5 +367,121 @@ describe('fetchGatewayToken', () => {
 
  await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('Token request failed: 401');
  });
+
+ it('lists available OAuth credentials in error when no match found', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow(
+ 'Available OAuth credentials: my-custom-identity'
+ );
+ });
+
+ it('suggests --identity-name in error when credentials exist but none match', async () => {
+ const projectSpecWithOtherCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithOtherCred,
+ });
+
+ await expect(fetchGatewayToken('myGateway', { configIO })).rejects.toThrow('--identity-name');
+ });
+ });
+
+ describe('--identity-name option', () => {
+ it('uses custom identity name instead of default convention', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_SECRET: 'custom-secret',
+ AGENTCORE_CREDENTIAL_MY_CUSTOM_IDENTITY_CLIENT_ID: 'custom-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'custom-token', expires_in: 1800 }),
+ } as Response);
+
+ const projectSpecWithCustomCred = {
+ ...defaultProjectSpecCustomJwt,
+ credentials: [
+ {
+ authorizerType: 'OAuthCredentialProvider',
+ name: 'my-custom-identity',
+ discoveryUrl: DISCOVERY_URL,
+ },
+ ],
+ };
+
+ const configIO = createMockConfigIO({
+ projectSpec: projectSpecWithCustomCred,
+ });
+
+ const result = await fetchGatewayToken('myGateway', {
+ configIO,
+ identityName: 'my-custom-identity',
+ });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'custom-token',
+ expiresIn: 1800,
+ });
+ });
+
+ it('falls back to default convention when identityName not provided', async () => {
+ vi.mocked(readEnvFile).mockResolvedValue({
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_SECRET: 'test-secret',
+ AGENTCORE_CREDENTIAL_MYGATEWAY_OAUTH_CLIENT_ID: 'test-client',
+ });
+
+ vi.mocked(global.fetch)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ token_endpoint: TOKEN_ENDPOINT }),
+ } as Response)
+ .mockResolvedValueOnce({
+ ok: true,
+ json: () => Promise.resolve({ access_token: 'test-token', expires_in: 3600 }),
+ } as Response);
+
+ const configIO = createMockConfigIO({
+ projectSpec: defaultProjectSpecCustomJwt,
+ });
+
+ const result = await fetchGatewayToken('myGateway', { configIO });
+
+ expect(result).toEqual({
+ url: GATEWAY_URL,
+ authType: 'CUSTOM_JWT',
+ token: 'test-token',
+ expiresIn: 3600,
+ });
+ });
  });
 });

src/cli/operations/fetch-access/fetch-gateway-token.ts

@@ -4,7 +4,7 @@ import type { TokenFetchResult } from './types';
 
 export async function fetchGatewayToken(
  gatewayName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<TokenFetchResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -71,6 +71,7 @@ export async function fetchGatewayToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 
  return {

src/cli/operations/fetch-access/fetch-runtime-token.ts

@@ -12,7 +12,10 @@ import type { OAuthTokenResult } from './oauth-token';
  * Returns true only if the managed OAuth credential exists in the project
  * spec AND the client secret is available in .env.local.
  */
-export async function canFetchRuntimeToken(agentName: string, options: { configIO?: ConfigIO } = {}): Promise<boolean> {
+export async function canFetchRuntimeToken(
+ agentName: string,
+ options: { configIO?: ConfigIO; identityName?: string } = {}
+): Promise<boolean> {
  try {
  const configIO = options.configIO ?? new ConfigIO();
  const projectSpec = await configIO.readProjectSpec();
@@ -21,7 +24,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  if (!agentSpec?.authorizerType || agentSpec.authorizerType !== 'CUSTOM_JWT') return false;
  if (!agentSpec.authorizerConfiguration?.customJwtAuthorizer) return false;
 
- const credName = computeManagedOAuthCredentialName(agentName);
+ const credName = options.identityName ?? computeManagedOAuthCredentialName(agentName);
  const hasCredential = projectSpec.credentials.some(
  c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName
  );
@@ -43,7 +46,7 @@ export async function canFetchRuntimeToken(agentName: string, options: { configI
  */
 export async function fetchRuntimeToken(
  agentName: string,
- options: { configIO?: ConfigIO; deployTarget?: string } = {}
+ options: { configIO?: ConfigIO; deployTarget?: string; identityName?: string } = {}
 ): Promise<OAuthTokenResult> {
  const configIO = options.configIO ?? new ConfigIO();
 
@@ -80,5 +83,6 @@ export async function fetchRuntimeToken(
  deployedState,
  targetName,
  credentials: projectSpec.credentials,
+ credentialName: options.identityName,
  });
 }

src/cli/operations/fetch-access/oauth-token.ts

@@ -31,17 +31,24 @@ export async function fetchOAuthToken(opts: {
  targetName: string;
  /** Project credentials list */
  credentials: { authorizerType: string; name: string }[];
+ /** Optional explicit credential name. When omitted, defaults to `<resourceName>-oauth`. */
+ credentialName?: string;
 }): Promise<OAuthTokenResult> {
  const { resourceName, jwtConfig, deployedState, targetName, credentials } = opts;
 
- const credName = computeManagedOAuthCredentialName(resourceName);
+ const credName = opts.credentialName ?? computeManagedOAuthCredentialName(resourceName);
 
  // Validate credential exists in project spec
  const credential = credentials.find(c => c.authorizerType === 'OAuthCredentialProvider' && c.name === credName);
  if (!credential) {
+ const availableOAuth = credentials.filter(c => c.authorizerType === 'OAuthCredentialProvider').map(c => c.name);
+ const availableHint =
+ availableOAuth.length > 0
+ ? ` Available OAuth credentials: ${availableOAuth.join(', ')}. Use --identity-name to specify one.`
+ : '';
  throw new Error(
- `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.` +
-`Re-create the resource with --client-id and --client-secret.`
+ `No managed OAuth credential found for '${resourceName}'. Expected credential '${credName}'.${availableHint}` +
+(availableOAuth.length === 0 ? ` Re-create the resource with --client-id and --client-secret.` : '')
  );
  }