JSON web token claims reference

When creating a secure embed, 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
• jti
• iat
• exp
• alg
• kid
• iss
• oauth_token
• connection_oauth_tokens
• eval_connection_id
• first_name
• last_name
• user_attributes
• account_type
• teams
• tenant
• ver
• aud

🚧

JWT claims 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

jti

JWT ID. A unique ID associated with the session.

Claim properties

iat

Issued at time, as number of seconds from epoch.

Claim properties

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

alg

Signing algorithm in use.

Usage notes

Must be HS256. If included, must be in the header.

Claim properties

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

iss

The issuer key.

Usage notes

• Must be the client ID of the credentials used to generate the JWT.

Claim properties

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.

Claim properties

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 API endpoint.
• As the values, provide encrypted OAuth tokens that the embed user will use to access data for that 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.

Claim properties

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 API endpoint.

Claim properties

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

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

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.

Claim properties

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.

Claim properties

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.

Claim properties

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 endpoint.

Claim properties

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

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