Skip to main content

Scopes
object

Contains functions used to manage scopes for your app.

This object is returned on authenticated Admin requests.

Anchor to scopesscopes

Provides utilities that apps can use to manage scopes for the app using the Admin API.

Anchor to query
query
() => Promise<>
required

Queries Shopify for the scopes for this app on this shop

Anchor to request
request
(scopes: string[]) => Promise<void>
required

Requests the merchant to grant the provided scopes for this app on this shop

Warning: This method performs a server-side redirect.

Anchor to revoke
revoke
(scopes: string[]) => Promise<>
required

Revokes the provided scopes from this app on this shop

Warning: This method throws an error if the provided optional scopes contains a required scope.

Was this section helpful?

Anchor to examplesExamples

Anchor to example-queryquery

Anchor to example-query-for-granted-scopesQuery for granted scopes

Call scopes.query to get scope details.

Was this section helpful?

Query for granted scopes

/app._index.tsx

import type { LoaderFunctionArgs } from "react-router";
import { useLoaderData } from "react-router";
import { authenticate } from "../shopify.server";
import { json } from "react-router";

export const loader = async ({ request }: LoaderFunctionArgs) => {
const { scopes } = await authenticate.admin(request);

const scopesDetail = await scopes.query();

return ({
hasWriteProducts: scopesDetail.granted.includes('write_products'),
});
};

export default function Index() {
const {hasWriteProducts} = useLoaderData<typeof loader>();

...
}

Anchor to example-requestrequest

Anchor to example-request-consent-from-the-merchant-to-grant-the-provided-scopes-for-this-appRequest consent from the merchant to grant the provided scopes for this app

Call scopes.request to request optional scopes.

Was this section helpful?

Request consent from the merchant to grant the provided scopes for this app

/app/routes/app.request.tsx

import type { ActionFunctionArgs } from "react-router";
import { useFetcher } from "react-router";
import { authenticate } from "../shopify.server";
import { json } from "react-router";

// Example of an action to POST a request to for optional scopes
export const action = async ({ request }: ActionFunctionArgs) => {
const { scopes } = await authenticate.admin(request);

const body = await request.formData();
const scopesToRequest = body.getAll("scopes") as string[];

// If the scopes are not already granted, a full page redirect to the request URL occurs
await scopes.request(scopesToRequest);
// otherwise return an empty response
return ({});
};

export default function Index() {
const fetcher = useFetcher<typeof action>();

const handleRequest = () => {
fetcher.submit({scopes: ["write_products"]}, {
method: "POST",
});
};

...
}

Anchor to example-revokerevoke

Anchor to example-revoke-optional-scopesRevoke optional scopes

Call scopes.revoke to revoke optional scopes.

Was this section helpful?

Revoke optional scopes

/app._index.tsx

import type { ActionFunctionArgs } from "react-router";
import { useFetcher } from "react-router";
import { authenticate } from "../shopify.server";
import { json } from "react-router";

// Example of an action to POST optional scopes to revoke
export const action = async ({ request }: ActionFunctionArgs) => {
const { scopes } = await authenticate.admin(request);

const body = await request.formData();
const scopesToRevoke = body.getAll("scopes") as string[];

const revokedResponse = await scopes.revoke(scopesToRevoke);

return (revokedResponse);
};

export default function Index() {
const fetcher = useFetcher<typeof action>();

const handleRevoke = () => {
fetcher.submit({scopes: ["write_products"]}, {
method: "POST",
});
};

...
}

Anchor to relatedRelated

Authenticate requests from Shopify Admin.Admin context