Storefront keys

Keys for the Storefront API, for a headless storefront your system sets up: publishable keys for browsers on the shop's own sites, secret keys for servers.

Reach them through $admin->keys. Reading needs the keys:read scope, creating and revoking keys:write. Admin keys can't be made here. Use the keys with the Storefront client.

List keys

$admin->keys->list(array $query = []): array

One page of the shop's active Storefront keys. A key issued to an app sees only the keys that app made. Read the next page with meta.nextCursor as cursor. Scope: keys:read.

Parameters

Parameter	Type
`$query`	`array`	The query fields below, by name.

Query fields

Parameter	Type	Description
`limit`	integer	At least 1. At most 100. Default `50`.
`cursor`	string	`meta.nextCursor` (or the cursor in `links.next`) of the previous page. At most 1000 characters.
`updatedSince`	string (date-time)	Records changed at or after this time (ISO 8601, any offset or `Z`), oldest change first, for incremental sync.

Returns

An array with data (a list of ApiKey), links and meta:

Field	Type	Description
`links`	object
`links.first`	null
`links.last`	null
`links.prev`	string (uri) or null
`links.next`	string (uri) or null
`meta`	object
`meta.path`	string (uri)
`meta.perPage`	integer
`meta.nextCursor`	string or null
`meta.prevCursor`	string or null
`data`	array of ApiKey
`data[].id`	integer
`data[].name`	string
`data[].type`	string	One of `publishable`, `secret`.
`data[].key`	string	A publishable key's full value; a secret key masked (`sk_live_…abcd`).
`data[].allowedOrigins`	array of string or null
`data[].oauthClientId`	string or null	The publishable key's sign-in client id.
`data[].redirectUris`	array of string (uri)
`data[].createdByApp`	string or null	The name of the app that made the key.
`data[].lastUsedAt`	string (date-time) or null
`data[].createdAt`	string (date-time) or null
`data[].updatedAt`	string (date-time) or null

Errors

Status	When
`401`	`invalid_api_key`: no active Admin key in `Authorization: Bearer`.
`403`	`admin_key_in_browser` (an `Origin` header was sent), `ip_not_allowed`, `plan_required`(the shop's plan lacks the Integration API, or the feature the endpoint needs), or`insufficient_scope`.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.

Example

$page = $admin->keys->list(['limit' => 50]);

foreach ($page['data'] as $key) {
    echo $key['name'], ' ', $key['type'];
}

Iterate over every key

$admin->keys->all(array $query = []): Generator

Every key matching the query, one at a time, fetching the next page as you read. It takes the same query as list, without cursor. Scope: keys:read.

Returns

A generator of ApiKey arrays, each:

Field	Type	Description
`[].id`	integer
`[].name`	string
`[].type`	string	One of `publishable`, `secret`.
`[].key`	string	A publishable key's full value; a secret key masked (`sk_live_…abcd`).
`[].allowedOrigins`	array of string or null
`[].oauthClientId`	string or null	The publishable key's sign-in client id.
`[].redirectUris`	array of string (uri)
`[].createdByApp`	string or null	The name of the app that made the key.
`[].lastUsedAt`	string (date-time) or null
`[].createdAt`	string (date-time) or null
`[].updatedAt`	string (date-time) or null

Example

foreach ($admin->keys->all() as $key) {
    $erp->saveKey($key['id'], $key['name'], $key['lastUsedAt']);
}

Create a key

$admin->keys->create(array $input, string|false|null $idempotencyKey = null): array

A publishable key (its allowed sites required, sign-in return addresses optional) or a secret key. The full value is in value, returned only now for a secret key. A key an app makes has the app's name appended; its publishable key may list only the origin of the shop's own site address, and its return addresses must be on that origin, under the site's path (422 site_origin_required). Scope: keys:write.

Parameters

Parameter	Type
`$input`	`array`	The key's fields, below.
`$idempotencyKey`	`string\|false\|null`	Your own `Idempotency-Key`, or `false` for none. One is made for you when null.

Request fields

Field	Type	Description
`name` required	string	At most 100 characters.
`type` required	string	One of `publishable`, `secret`.
`allowedOrigins`	array of string	Required for a publishable key, prohibited for a secret one. Site origins, such as `https://www.example.com`. At most 10 items.
`redirectUris`	array of string or null	Publishable keys only. Sign-in return addresses on the allowed sites. At most 5 items.

Returns

A CreatedApiKey array: the key in data, and its full value in value.

Field	Type	Description
`data`	ApiKey
`data.id`	integer
`data.name`	string
`data.type`	string	One of `publishable`, `secret`.
`data.key`	string	A publishable key's full value; a secret key masked (`sk_live_…abcd`).
`data.allowedOrigins`	array of string or null
`data.oauthClientId`	string or null	The publishable key's sign-in client id.
`data.redirectUris`	array of string (uri)
`data.createdByApp`	string or null	The name of the app that made the key.
`data.lastUsedAt`	string (date-time) or null
`data.createdAt`	string (date-time) or null
`data.updatedAt`	string (date-time) or null
`value`	string	The key's full value (`pk_live_…` or `sk_live_…`).

Errors

Status	When
`401`	`invalid_api_key`: no active Admin key in `Authorization: Bearer`.
`403`	`admin_key_in_browser` (an `Origin` header was sent), `ip_not_allowed`, `plan_required`(the shop's plan lacks the Integration API, or the feature the endpoint needs), or`insufficient_scope`.
`409`	`idempotency_in_progress`: a request with this `Idempotency-Key` is still running. Retry with the same key after `Retry-After` seconds; the first answer is then replayed.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.

Example

$created = $admin->keys->create([
    'name' => 'Laravel storefront',
    'type' => 'secret',
]);
$secret = $created['value']; // Shown this once.

Revoke a key

$admin->keys->revoke(int $id): void

The key stops at once, and shoppers signed in through its client are signed out. Scope: keys:write.

Parameters

Parameter	Type
`$id`	`int`	The key's id.

Returns

Nothing.

Errors

Status	When
`401`	`invalid_api_key`: no active Admin key in `Authorization: Bearer`.
`403`	`admin_key_in_browser` (an `Origin` header was sent), `ip_not_allowed`, `plan_required`(the shop's plan lacks the Integration API, or the feature the endpoint needs), or`insufficient_scope`.
`404`	`not_found`: the shop has no such record.
`409`	`idempotency_in_progress`: a request with this `Idempotency-Key` is still running. Retry with the same key after `Retry-After` seconds; the first answer is then replayed.
`422`	Validation errors (`{ message, errors }`), or an idempotency refusal(`idempotency_key_reused`, `idempotency_key_invalid`).
`429`	Rate limited.