Menu

Api Keys API Routes

API keys can be used for authentication or resource-scoping.

A secret API key can be used to authenticate admin users. A publishable API key can be used to scope client requests to one or more sales channels.

These API routes allow admin users to manage both publishable and secret API keys.

GET /admin/api-keys#

List API Keys

Retrieve a list of API keys. The API keys can be filtered by fields such as id. The API keys can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
A search term to search the API keys' searchable properties.
idstring | string[]Optional
Filter by an API key's ID.
titlestring | string[]Optional
Filter by an API key's title.
tokenstring | string[]Optional
Filter by an API key's token.
type"secret" | "publishable"Optional
Filter by the API key's type.
created_atobjectOptional
Filter by the API key's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the API key's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the API key's deletion date. Accepts the filter operators.
revoked_atobjectOptional
Filter by the API key's revoke date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned in the list.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total count of items.
api_keysobject[]
The list of API keys.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/api-keys#

Create Api Key

Create a secret or publishable API key. A secret API key is used for admin authentication.

A publishable API key is used by client applications to set the scope of the request.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

titlestring
The API key's title.
type"publishable" | "secret"
The API key's type. Use secret for a user's API key; Use publishable for Publishable API keys.

Request examples

Responses

200 OK

api_keyobject
The API key's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/api-keys/{id}#

Get API Key

Retrieve an API key by its ID. You can expand the API key's relations or select the fields that should be returned using the query parameters.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The API key's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

api_keyobject
The API key's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/api-keys/{id}#

Update an API Key

Update an API key's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The API key's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

titlestring
The API key's title.

Request examples

Responses

200 OK

api_keyobject
The API key's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/api-keys/{id}#

Delete an Api Key

Delete a publishable or secret API key.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The API key's ID.

Request examples

Responses

200 OK

idstring
The API key's ID.
objectstring
The name of the object that was deleted.

Default: "api_key"

deletedboolean
Whether the API key was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/api-keys/{id}/revoke#

Revoke API Key

Revokes an API key. If the API key is a secret, it can't be used for authentication anymore. If it's publishable, it can't be used by client applications.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The API key's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

revoke_innumberOptional
The time in seconds to revoke the API key after. If not set, the API key is revoked immediately.

Request examples

Responses

200 OK

api_keyobject
The API key's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/api-keys/{id}/sales-channels#

Manage Sales Channels of a Publishable API Key

Manage the sales channels of a publishable API key, either to associate them or remove them from the API key.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The API key's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

addstring[]Optional
The IDs of an entity to add to the other.
removestring[]Optional
The IDs of an entity to remove from the other.

Request examples

Responses

200 OK

api_keyobject
The API key's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page