Admin API

Project routing

The public GraphQL URL includes the project identifier before the API surface. Use the same project segment for every request made by an integration.

At the gateway, Thor resolves that segment and scopes resolvers, permission checks, database connections, and downstream services to the selected project.

• /{project}/admin/graphql for Admin API requests
• /{project}/storefront/graphql for Storefront API requests

Authentication

The Admin API supports user access tokens and API keys. Choose one authentication method per request.

For a signed-in Admin user, send Authorization: Bearer <token>. This preserves the user’s identity and permissions. Operations that require a human identity, including product and translation exports or imports, must use this method.

For server-to-server access, create an API key in the Thor Dashboard and send it as X-Api-Key: <api-key>. Do not send an API key as a bearer token.

Keep credentials in server-side secret storage and grant only the permissions the integration needs. Both authentication methods remain scoped by the project URL and permission checks.

GraphQL basics

The Admin and Storefront APIs use the same GraphQL fundamentals. Name every operation, declare external values as variables, and select only the fields the caller needs. Queries read data. Mutations change data and commonly accept one typed input object.

Field names, arguments, and nullability are defined independently by each schema. Use the generated API reference as the source of truth, and keep project routing and credentials separate from the GraphQL document.

Fragments reuse selections without making another request. Use inline fragments and __typename when a field returns an interface or union.

Pagination

List fields generally return cursor connections. Use nodes when you only need records, or edges { cursor node } when each item's cursor is useful. Request pageInfo with the page.

For forward pagination, request first items and pass the returned endCursor to after. For backward pagination, use last, before, andstartCursor. A page can contain at most 100 items. Do not pass a first or last value greater than 100.

Treat cursors as opaque. Keep filters, sorting, and Storefront commerce context unchanged while traversing a connection, and restart from the first page after any of those inputs changes.

Typed IDs

Thor IDs are opaque strings with a resource prefix, such as product_..., vid_..., cart_..., or order_.... The prefix lets Thor reject an ID passed to the wrong argument early.

Store and pass the complete value unchanged. Do not generate IDs, decode their payloads, replace prefixes, or infer properties from them. Cursors are also opaque strings, but they identify positions in a connection rather than resources.

The generic node(id: ID!) query can refetch supported resources. Resource-specific inputs still require the correct ID type.

Errors

Process every applicable failure channel:

1. HTTP and transport failures report whether the request reached and was accepted by the GraphQL service.
2. Top-level GraphQL errors report parsing, validation, authorization, or field-execution failures. A response can contain both partial data and errors.
3. Many mutations expose typed business errors in their payload. A 200 OK response can still represent a rejected business operation.

Select __typename for typed errors and use it as the dispatch key. Do not parse human-readable messages to control application behavior.

Shared search filtering is documented in the search query language. Storefront filter construction is covered in facets.