Introspect a token

Target Audience: Developers & Non technical users

Goal

Decode a signed Toucan AI token to inspect its internal payload and verify its validity.

---

Prerequisites

• A Toucan AI account with active access.

• A previously generated token (sandbox or production).

---

Steps

1. Access the Embed settings

• Click on the Settings button in the main navigation menu.

• Select the Embed & access tab to view the integration and security configurations.

2. Locate the introspection tool

• Scroll to the Token Introspection section.

• This interface is designed to parse and display the metadata of any Toucan AI authentication token.

3. Input and decode the token

• Copy the token string you wish to examine.

• Paste the string into the JWT Token field.

• Click the Introspect Token button to trigger the decoding process.

4. Review token metadata

The tool will display the following decoded parameters:

• User Information: Includes the distinctId and the assigned role.

• Custom Attributes: Displays all key-value pairs used for Row-Level Security (e.g., department: "finance").

• Permissions: Lists granular access rights like can_view, can_edit, or can_query.

• Expiration: Shows the exact timestamp when the token will become invalid.

5. Validate results

• Verify that the attributes match the intended user context.

• If the data is incorrect or the status indicates the token has expired, generate a new credential via the sandbox or API.

---

Conclusion

Token introspection provides a non-destructive way to audit user identity propagation and permission scoping. Ensuring token accuracy at this stage prevents unauthorized access or "Failed to load" errors in the embedded environment.

Suggested Next Step: How-to: Embed a dashboard or How-to: Configure Row-Level Security (RLS)