> For the complete documentation index, see [llms.txt](https://docs.toucanai.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucanai.cloud/embed/authentication/how-to/token-introspection.md).

# Introspect a token

{% hint style="info" %}
**Target Audience**: Developers & Non technical users
{% endhint %}

### Goal

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

***

### Prerequisites

* A [Toucan AI account](/getting-started/quick-start/subscribe-to-toucan.md) with active access.
* A previously [generated token](/embed/authentication/how-to/authentication-and-tokens.md) (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.

<figure><img src="/files/q4iuwOWIikiTEyNgIQNx" alt="Token Introspection"><figcaption></figcaption></figure>

***

### 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](/embed/embedding-overview/how-to/embed-a-dashboard.md) or [How-to: Configure Row-Level Security (RLS)](/embed/permissions-and-row-level-security/how-to/apply-rls-to-your-database.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toucanai.cloud/embed/authentication/how-to/token-introspection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.