Session TokenAPI
The API for interacting with session tokens.
Anchor to standardapiStandardApi
The base API object provided to this and other customer-account extension targets.
- Anchor to sessionTokensessionTokenrequired
Provides access to session tokens, which can be used to verify token claims on your app's server.
See session token examples for more information.
Docs_Standard_SessionTokenApi
- sessionToken
Provides access to session tokens, which can be used to verify token claims on your app's server. See [session token examples](/docs/api/customer-account-ui-extensions/apis/session-token#examples) for more information.
SessionToken
export interface Docs_Standard_SessionTokenApi
extends Pick<StandardApi<any>, 'sessionToken'> {}SessionToken
- get
Requests a session token that hasn't expired. You should call this method every time you need to make a request to your backend in order to get a valid token. This method will return cached tokens when possible, so you don’t need to worry about storing these tokens yourself.
() => Promise<string>
export interface SessionToken {
/**
* Requests a session token that hasn't expired. You should call this method every
* time you need to make a request to your backend in order to get a valid token.
* This method will return cached tokens when possible, so you don’t need to worry
* about storing these tokens yourself.
*/
get(): Promise<string>;
}Anchor to useSessionTokenuse
Returns a the session token API object.
- get() => Promise<string>
Requests a session token that hasn't expired. You should call this method every time you need to make a request to your backend in order to get a valid token. This method will return cached tokens when possible, so you don’t need to worry about storing these tokens yourself.
SessionToken
UseSessionTokenGeneratedType
Provides access to session tokens, which can be used to verify token claims on your app's server.
SessionTokenexport function useSessionToken<
Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): SessionToken {
const api = useApi<Target>();
const extensionTarget = api.extension.target;
if (!('sessionToken' in api)) {
throw new ExtensionHasNoFieldError('sessionToken', extensionTarget);
}
return api.sessionToken;
}SessionToken
- get
Requests a session token that hasn't expired. You should call this method every time you need to make a request to your backend in order to get a valid token. This method will return cached tokens when possible, so you don’t need to worry about storing these tokens yourself.
() => Promise<string>
export interface SessionToken {
/**
* Requests a session token that hasn't expired. You should call this method every
* time you need to make a request to your backend in order to get a valid token.
* This method will return cached tokens when possible, so you don’t need to worry
* about storing these tokens yourself.
*/
get(): Promise<string>;
}Using a session token with fetch()
examples
Using a session token with fetch()
React
import {useEffect} from 'react'; import { reactExtension, Banner, useApi, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => <Extension />, ); function Extension() { const {sessionToken} = useApi(); useEffect(() => { async function queryApi() { // Request a new (or cached) session token from Shopify const token = await sessionToken.get(); console.log('sessionToken.get()', token); const apiResponse = await fetchWithToken(token); // Use your response console.log('API response', apiResponse); } function fetchWithToken(token) { const result = fetch( 'https://myapp.com/api/session-token', { headers: { Authorization: `Bearer ${token}`, }, }, ); return result; } queryApi(); }, [sessionToken]); return ( <Banner>See console for API response</Banner> ); }JavaScript
import { extension, Banner, BlockStack, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, {sessionToken}) => { async function queryApi() { // Request a new (or cached) session token from Shopify const token = await sessionToken.get(); console.log(token); const apiResponse = await fetchWithToken(token); // Use your response console.log(apiResponse); } function fetchWithToken(token) { const result = fetch( 'https://myapp.com/api/session-token', { headers: { Authorization: `Bearer ${token}`, }, }, ); return result; } queryApi(); root.appendChild( root.createComponent(Banner, { title: 'Session Token Extension', }), ); }, );
Anchor to examplesExamples
Anchor to example-session-token-claimsSession token claims
The contents of the token are signed using your shared app secret. The optional sub claim contains the customer's gid if they are logged in and your app has permission to read customer accounts. For example, a loyalty app that needs to check a customer's point balance can use the sub claim to verify the customer's account.
Session token claims
examples
Session token claims
description
The contents of the token are signed using your shared app secret. The optional `sub` claim contains the customer's `gid` if they are logged in and your app has permission to read customer accounts. For example, a loyalty app that needs to check a customer's point balance can use the `sub` claim to verify the customer's account.
Session token claims
{ // Shopify URL "dest": "store-name.myshopify.com", // The Client ID of your app "aud": "<clientId>", // When the token expires. Set at 5 minutes. "exp": 1679954053, // When the token was actived "nbf": 1679953753, // When the token was issued "iat": 1679953753, // A unique identifier (a nonce) to prevent replay attacks "jti": "6c992878-dbaf-48d1-bb9d-6d9b59814fd1", // Optional claim present when a customer is logged in and your app has permissions to read customer data "sub": "gid://shopify/Customer/<customerId>" }