Authentication and API Requests

This guide builds on the APIs guide and covers additional authentication details, practical request patterns, and troubleshooting for local development.

Local password-grant shortcut

The APIs guide uses integrations with client_credentials, which should remain the default approach.

For local development only, you can also obtain an Admin API token with the default Administration credentials:

curl -X POST "http://localhost:8000/api/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "client_id": "administration",
    "scopes": "write",
    "username": "admin",
    "password": "shopware"
  }'

Example response:

{
  "token_type": "Bearer",
  "expires_in": 600,
  "access_token": "...",
  "refresh_token": "..."
}

Use this only as a local shortcut. For integrations and reproducible setups, prefer client_credentials as described in the APIs guide.

Impersonate a customer

Support tooling can open a Store API context as an existing customer without knowing the customer's password.

1. With an Admin API token belonging to a user with api_proxy_imitate-customer ACL privilege, request a short-lived token:

   POST /api/_proxy/generate-imitate-customer-token
   Authorization: Bearer ADMIN_API_TOKEN
   Content-Type: application/json
   
   {
     "salesChannelId": "SALES_CHANNEL_ID",
     "customerId": "CUSTOMER_ID"
   }

2. Redeem the token through the Store API. The response returns the new context token in the sw-context-token response header; use that header value for subsequent requests:

   POST /store-api/account/login/imitate-customer
   sw-access-key: SALES_CHANNEL_ACCESS_KEY
   Content-Type: application/json
   
   {
     "token": "IMPERSONATION_TOKEN_FROM_STEP_1",
     "customerId": "CUSTOMER_ID",
     "userId": "ADMIN_USER_ID"
   }

WARNING

Impersonation performs a real customer login, so login events fire, and cart changes affect the customer's cart. Grant the ACL privilege only to trusted users and use this flow only for support or testing.

Prefer search endpoints for real requests

For most real Admin API work, prefer search endpoints over simple entity listing routes.

Instead of:

curl "http://localhost:8000/api/product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Use:

curl -X POST "http://localhost:8000/api/search/product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Search endpoints support:

• filtering
• sorting
• pagination
• loading associations (loading relations of the entity in the same request)

Download the OpenAPI schema

Shopware exposes OpenAPI schema endpoints for both Admin API and Store API. If you want to work with the raw Admin API schemas instead of the browser reference, you can download them directly.

OpenAPI specification

Use the OpenAPI spec when you need the full API contract for tooling, client generation, or inspection of available endpoints.

curl -X GET "http://localhost:8000/api/_info/openapi3.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o openapi.json

This saves the file as openapi.json in your current working directory.

To verify where it was written and inspect it:

pwd
ls -lh openapi.json
head -n 5 openapi.json

Entity schema

Use the entity schema when you need metadata about entities and their fields:

curl -X GET "http://localhost:8000/api/_info/open-api-schema.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o entity-schema.json

To verify the downloaded file:

pwd
ls -lh entity-schema.json
head -n 5 entity-schema.json

WARNING

Due to security restrictions, your APP_ENV environment variable must be set to dev to access the specifications described below.

Available raw schema endpoints:

• OpenAPI spec: /(api|store-api)/_info/openapi3.json.
• Entity schema: /(api|store-api)/_info/open-api-schema.json.

Troubleshooting local request failures

If you encounter errors like:

• Table 'shopware.system_config' doesn't exist
• Table 'shopware.plugin' doesn't exist
• HTTP 500 on /api/_info/openapi3.json

your database may not be initialized.

Run:

docker compose exec web bin/console system:install --create-database --basic-setup

Next steps

Learn how to structure queries using:

• Search Criteria: Encapsulates the entire search definition in one generic object.
• Request Headers: Covers optional headers that customize API requests.
• Partial Data Loading: Limits responses to the fields you actually need.