Medusa V2 Admin API Reference

This API reference includes Medusa's Admin APIs, which are REST APIs exposed by the Medusa application. They are used to perform admin functionalities or create an admin dashboard to access and manipulate your commerce store's data.

All API Routes are prefixed with /admin. So, during development, the API Routes will be available under the path http://localhost:9000/admin. For production, replace http://localhost:9000 with your Medusa application URL.

Authentication

There are three ways to send authenticated requests to the Medusa server: Using a JWT token in a bearer authorization header, using an admin user's API token, or using a cookie session ID.

Bearer Authorization with JWT Tokens

Use a JWT token in a request's bearer authorization header to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications.

How to Obtain the JWT Token

JWT tokens are obtained by sending a request to the authentication route passing it the user's email and password in the request body.

For example:

Code
1curl -X POST '{backend_url}/auth/user/emailpass' \2-H 'Content-Type: application/json' \3--data-raw '{4  "email": "user@example.com",5  "password": "supersecret"6}'

If authenticated successfully, an object is returned in the response with the property token being the JWT token.

Learn more about the authentication route here

How to Use the JWT Token

Pass the JWT token in the authorization bearer header:

Terminal
❯Authorization: Bearer {jwt_token}

API Token

Use a user's API Token to send authenticated requests.

How to Create an API Token for a User

Use the Create API Key API Route to create an API token:

Code
1curl --location 'localhost:9000/admin/api-keys' \2--header 'Content-Type: application/json' \3--header 'Authorization: Bearer {jwt_token}' \4--data '{5    "title": "my token",6    "type": "secret"7}'

An api_key object is returned in the response. You need its token property.

How to Use the API Token

The API token can be used by providing it in a basic authorization header:

Terminal
❯Authorization: Basic {api_key_token}

Cookie Session ID

When you authenticate a user and create a cookie session ID for them, the cookie session ID is passed automatically when sending the request from the browser, or with tools like Postman.

How to Obtain the Cookie Session

To obtain a cookie session ID, you must have a JWT token for bearer authentication.

Then, send a request to the session authentication API route. To view the cookie session ID, pass the -v option to the curl command:

Code
1curl -v -X POST '{backend_url}/auth/session' \2--header 'Authorization: Bearer {jwt_token}'

The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:

Terminal
❯Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;

How to Use the Cookie Session ID in cURL

Copy the value after connect.sid (without the ; at the end) and pass it as a cookie in subsequent requests as the following:

Code
1curl '{backend_url}/admin/products' \2-H 'Cookie: connect.sid={sid}'

Where {sid} is the value of connect.sid that you copied.

Including Credentials in the Fetch API

If you're sending requests using JavaScript's Fetch API, you must pass the credentials option with the value include to all the requests you're sending. For example:

Code
1fetch(`<BACKEND_URL>/admin/products`, {2  credentials: "include",3})

HTTP Compression

If you've enabled HTTP Compression in your Medusa configurations, and you want to disable it for some requests, you can pass the x-no-compression header in your requests:

Terminal
❯x-no-compression: true

Select Fields and Relations

Many API Routes accept a fields query that allows you to select which fields and relations should be returned in a record. Fields and relations are separated by a comma ,.

For example:

Code
1curl 'localhost:9000/admin/products?fields=title,handle' \2-H 'Authorization: Bearer {jwt_token}'

This returns only the title and handle fields of a product.

Fields Operator

By default, only the selected fields and relations are returned in the response.

Before every field or relation, you can pass one of the following operators to change the default behavior:

• +: Add the field to the fields returned by default. For example, +title returns the title field along with the fields returned by default.
• -: Remove the field from the fields returned by default. For example, -title removes the title field from the fields returned by default.

Select Relations

To select a relation, pass to fields the relation name prefixed by *. For example:

Code
1curl 'localhost:9000/admin/products?fields=*variants' \2-H 'Authorization: Bearer {jwt_token}'

This returns the variants of each product.

Select Fields in a Relation

The * prefix selects all fields of the relation's data model.

To select a specific field, pass a .<field> suffix instead of the * prefix. For example, variants.title.

To specify multiple fields, pass each of the fields with the <relation>.<field> format, separated by a comma.

For example:

Code
1curl 'localhost:9000/admin/products?fields=variants.title,variants.sku' \2-H 'Authorization: Bearer {jwt_token}'

This returns the variants of each product, but the variants only have their id, title, and sku fields. The id is always included.

Query Parameter Types

This section covers how to pass some common data types as query parameters.

Strings

You can pass a string value in the form of <parameter_name>=<value>.

For example:

Code