> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://help.sigmacomputing.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server. # JSON web token claims reference > Reference for JWT claims used with Sigma secure embeds to pass user identity, teams, attributes, and other settings. When [creating a secure embed](/docs/create-an-embed-api-with-json-web-tokens), use these claims when constructing the JSON web token (JWT) to pass information in your embed URL. Some claims must be specified in the header and the remainder must be specified in the payload before being signed. * [`sub`](#sub) * [`jti`](#jti) * [`iat`](#iat) * [`exp`](#exp) * [`alg`](#alg) * [`kid`](#kid) * [`iss`](#iss) * [`oauth_token`](#oauth_token) * [`connection_oauth_tokens`](#connection_oauth_tokens) * [`eval_connection_id`](#eval_connection_id) * [`first_name`](#first_name) * [`last_name`](#last_name) * [`user_attributes`](#user_attributes) * [`account_type`](#account_type) * [`teams`](#teams) * [`tenant`](#tenant) * [`ver`](#ver) * [`aud`](#aud) [JWT claims](/docs/json-web-token-claims-reference) are specific to a user, not a session. Do not use user-specific claims (such as teams, account type, or user attribute values) to manage what a user in a given *session* can view in an embed. Instead, manage access on the user level. Each user must have their own account to access the embed with the correct access level and permissions. Use consistent claim values for the same embed user across different secure embeds. ## `sub` The email address of the user logging in. ### Usage notes Email addresses must be RFC-1035 compliant, and not include white space or unsupported characters, such as underscores. ### Claim properties | | | | ------------- | -------- | | **Required?** | Required | | **Type** | string | ## `jti` JWT ID. A unique ID associated with the session. ### Claim properties | | | | ------------- | -------- | | **Required?** | Required | | **Type** | string | ## `iat` Issued at time, as number of seconds from epoch. ### Claim properties | | | | ------------- | -------- | | **Required?** | Required | | **Type** | number | ## `exp` Expired at time, as number of seconds from epoch. ### Usage notes * The difference between the value specified for `exp` and the value specified for `iat` cannot exceed 30 days (2592000 seconds). ### Claim properties | | | | ------------- | -------- | | **Required?** | Required | | **Type** | number | ## `alg` Signing algorithm in use. ### Usage notes Must be `HS256`. If included, must be in the header. ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `kid` The embed client ID. ### Usage notes * Must be in the header. * Must be the client ID of the credentials used to generate the JWT. ### Claim properties | | | | ------------- | -------- | | **Required?** | Required | | **Type** | string | ## `iss` The issuer key. ### Usage notes * Must be the client ID of the credentials used to generate the JWT. ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `oauth_token` The OAuth token to use when using organization-level OAuth connections. ### Usage notes * This token must be encrypted with the embed secret. For information on how to encrypt your OAuth tokens so that they are compatible with the embed API, see Sigma Node.js Embed SDK. For more details about using the `oauth_token` claim to restrict access to data, see [Use OAuth for your secure embed](/docs/restrict-access-to-data-in-embedded-content#use-oauth-for-your-secure-embed). ### Claim properties | | | | ------------- | ----------------------------------- | | **Required?** | Optional | | **Type** | string | | **Version** | Can only be used with `ver: "1.1"`. | ## `connection_oauth_tokens` The OAuth token to use when using connection-level OAuth connections. ### Usage notes * Can provide multiple key-value pairs. * As the keys, provide the connection ID. Retrieve the connection ID from the [List connections](/reference/list-connections) API endpoint. * As the values, provide OAuth tokens encrypted with the client secret used to sign the JWT. When a user accesses the application, they use the provided OAuth token to authenticate to the data connection. For information on how to encrypt your OAuth tokens so that they are compatible with the embed API, see Sigma Node.js Embed SDK. For more details about using the `connection_oauth_tokens` claim to restrict access to data, see [Use OAuth for your secure embed](/docs/restrict-access-to-data-in-embedded-content#use-oauth-for-your-secure-embed). ### Claim properties | | | | ------------- | ----------------------------------- | | **Required?** | Optional | | **Type** | `Record` | | **Version** | Can only be used with `ver: "1.1"`. | ## `eval_connection_id` The connection to use instead of the connection that the workbook is associated with. ### Usage notes * If you use write-back features, such as input tables, materialization, or Python, you cannot use this claim to perform connection switching. * Retrieve the connection ID from the [List connections](/reference/list-connections) API endpoint. * Cannot be used with connections authenticated with OAuth. ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `first_name` First name for the embed user. ### Usage notes Only include this claim for embed users. Internal users accessing your embed use their name in Sigma. ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `last_name` Last name for the embed user. ### Usage notes Only include this claim for embed users. Internal users accessing your embed use their name in Sigma. ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `user_attributes` User attributes for the embed user. ### Usage notes * Pass multiple attributes in this format: `{"attribute1":"value1","attribute2":"value2"}`. * If the attribute name includes spaces or special characters, do not URL-encode the attribute name. * Only include this claim for embed users. Internal users accessing your embed use the attributes assigned to them in Sigma. For more details about using user attributes to restrict access to data for users, see [Restrict access to data in embedded content](/docs/restrict-access-to-data-in-embedded-content). ### Claim properties | | | | ------------- | ----------------------- | | **Required?** | Optional | | **Type** | `Record` | ## `account_type` Account type for the embed user. ### Usage notes * Only include this claim for embed users. Internal users accessing your embed use the account type assigned to them. * If not specified for an embed user, Sigma defaults to the highest account type. For more details about using the `account_type` claim to manage embed users, see [Manage access to a secure embed](/docs/manage-access-to-a-secure-embed). ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `teams` Teams that the embed user is a part of. ### Usage notes * Pass multiple teams in this format: `["team1", "team2"]`. * If a team name includes spaces or special characters, do not URL-encode the team name. * Only include this claim for embed users. Internal users accessing your embed use the teams that they are assigned in Sigma. For more details about using the `teams` claim to manage embed users, see [Manage access to a secure embed](/docs/manage-access-to-a-secure-embed). ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `tenant` The UUID of the tenant organization that you want to authenticate to. ### Usage notes * Retrieve the tenant organization ID by calling the [List tenants](/reference/list-tenants) endpoint. ### Claim properties | | | | ------------- | ----------------------------------- | | **Required?** | Optional | | **Type** | string | | **Version** | Can only be used with `ver: "1.1"`. | ## `ver` JWT version number. ### Usage notes * The only accepted values are `"1.0"` or `"1.1"`. * If not provided, `"1.0"` is assumed. ### Claim properties | | | | ------------- | -------- | | **Required?** | Optional | | **Type** | string | ## `aud` The audience claim. ### Usage notes * If used with `ver: "1.0"`, is ignored. * If used with `ver: "1.1"`, must be `sigmacomputing`. ### Claim properties | | | | ------------- | ---------------------------------------------------- | | **Required?** | Optional for `ver: "1.0"`, Required for `ver: "1.1"` | | **Type** | string |