Skip to main content

Admin API Overview

The Admin API is a GraphQL API designed for backend operations and administrative tasks. Use it to manage your complete e-commerce infrastructure, including inventory, orders, configurations, users, and more.

Use Cases​

The Admin API is ideal for:

  • Inventory Management: Create, update, and manage your product catalog, items, listings, and stock levels
  • Order Processing: Handle orders, fulfillments, shipping, and order lifecycle management
  • Media Management: Upload and manage images, assets, and media files

Best for: Backend services, administrative dashboards, inventory management systems, internal tools, and server-to-server integrations.

Endpoint​

The Admin API endpoint is:

https://api-admin.common-ground.io/graphql

Authentication​

The Admin API authenticates requests using a secret key. You pass your secret key directly in the Authorization header as a Bearer token.

Secret Key​

Your secret key is created and managed in the admin panel of your Common Ground store.

Secret keys must be stored securely and never exposed in client-side code. Use them only for server-to-server communication.

Authentication Headers​

Include the following headers in all Admin API requests:

  • Authorization: Bearer sk-... - Your secret key
Authorization: Bearer sk-...

Rate Limits​

Admin API access is limited to 30 requests per minute.

Rate Limit Headers:

The API returns rate limit information in response headers:

  • RateLimit-Limit - Maximum requests allowed in the window
  • RateLimit-Remaining - Remaining requests in the current window
  • RateLimit-Reset - Time when the rate limit window resets

Implement exponential backoff when you receive 429 Too Many Requests responses. Cache responses when possible to reduce API calls, and batch operations when available to minimize request count.

Query Complexity​

Keep operations shallow and close to the examples in these docs:

  • Prefer 3–4 levels of nesting (for example root field → object → nested fields). Deeper nesting is rarely needed for Admin workflows and may be rejected
  • Request only the fields you need
  • Use pagination for large datasets
  • Use filters to narrow results

Follow the query and mutation examples throughout the Admin API documentation—they reflect the nesting depth and field selection patterns that work well in production.

Schema​

The Admin API uses a comprehensive GraphQL schema that includes:

  • Queries: Read operations for inventory, orders, users, configurations, and more
  • Mutations: Write operations for creating, updating, and deleting resources
  • Types: Rich type system for items, orders, users, configurations, and related entities
  • Input Types: Structured inputs for mutations and filters
  • Enums: Predefined sets of values for statuses, types, and categories

Download the Schema:

You can download the complete Admin API schema file for use with GraphQL tools, code generators, and IDEs:

Download Admin API Schema

Schema introspection from the GraphQL endpoint is disabled. Use the downloadable schema file instead.

Next Steps​