Skip to content

Commit deff754

Browse files
docs: add delegation and impersonation example for CTE (#1111)
Adds a delegation and impersonation example to the CTE section in EXAMPLES.md, showing how to use `customTokenExchange` with `actor_token` and `actor_token_type`. Mirrors [auth0-spa-js#1611](auth0/auth0-spa-js#1611), adapted for the React hook-based API.
1 parent 0413bde commit deff754

1 file changed

Lines changed: 53 additions & 0 deletions

File tree

EXAMPLES.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,59 @@ export default TokenExchange;
215215
- The audience and scope can be provided directly in the options or will fall back to SDK defaults
216216
- **State Management:** This method triggers the `GET_ACCESS_TOKEN_COMPLETE` action internally upon completion. This ensures that the SDK's `isLoading` and `isAuthenticated` states behave identically to the standard `getAccessTokenSilently` flow.
217217

218+
### Delegation and Impersonation
219+
220+
Use `customTokenExchange` when one principal needs to act on behalf of another — for example, an AI agent acting on behalf of a user. Unlike `loginWithCustomTokenExchange`, this method has no side effects: it does not update the session or affect `isAuthenticated` / `user`.
221+
222+
Pass `actor_token` and `actor_token_type` alongside the subject token to identify the acting party per [RFC 8693](https://tools.ietf.org/html/rfc8693):
223+
224+
```jsx
225+
import React, { useState } from 'react';
226+
import { useAuth0 } from '@auth0/auth0-react';
227+
228+
const DelegatedAction = () => {
229+
const { customTokenExchange } = useAuth0();
230+
const [accessToken, setAccessToken] = useState(null);
231+
const [error, setError] = useState(null);
232+
233+
const handleDelegation = async (userToken, agentToken) => {
234+
try {
235+
const tokenResponse = await customTokenExchange({
236+
subject_token: userToken,
237+
subject_token_type: 'urn:acme:user-token',
238+
actor_token: agentToken,
239+
actor_token_type: 'https://idp.example.com/token-type/agent',
240+
audience: 'https://api.example.com',
241+
});
242+
243+
setAccessToken(tokenResponse.access_token);
244+
setError(null);
245+
246+
// Use tokenResponse.access_token to call a downstream API
247+
// The current user session is unchanged
248+
} catch (e) {
249+
console.error('Delegation failed:', e);
250+
setError(e.message);
251+
}
252+
};
253+
254+
return (
255+
<div>
256+
<button onClick={() => handleDelegation('<USER_TOKEN>', '<AGENT_TOKEN>')}>
257+
Act on Behalf of User
258+
</button>
259+
{accessToken && <div>Delegation successful!</div>}
260+
{error && <div>Error: {error}</div>}
261+
</div>
262+
);
263+
};
264+
265+
export default DelegatedAction;
266+
```
267+
268+
[Token Exchange Documentation](https://auth0.com/docs/authenticate/login/token-exchange)
269+
[RFC 8693 Spec](https://tools.ietf.org/html/rfc8693)
270+
218271
## Protecting a route in a `react-router-dom v6` app
219272

220273
We need to access the `useNavigate` hook so we can use `navigate` in `onRedirectCallback` to return us to our `returnUrl`.

0 commit comments

Comments
 (0)