> For the complete documentation index, see [llms.txt](https://docs.globo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.globo.io/pre-order/app-api/rest-api/authentication.md).

# Authentication

The Authentication API is the entry point for securing access to the platform. Before accessing protected APIs, each request must include a valid access token obtained through the authentication endpo

### <mark style="color:red;">\* Required Request</mark>

#### Headers

`Authorization: Bearer ••••••••••••••••••••••••••••••••••••`

All API requests must include the required authentication headers: `Authorization: Bearer token` (your API key)

### Create App API Key

Go to Preorder App -> **Settings** page -> **Mail SMTP & API**

<figure><img src="https://2477033452-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRtV458Onax2rMaEUV2SD%2Fuploads%2FEdx59UH3JyZ7VyYOx9tx%2Fimage.png?alt=media&amp;token=db6621dc-7726-4750-8f65-aca06303dbb6" alt=""><figcaption></figcaption></figure>

#### Create APP API key -> select scope & exprise

<figure><img src="https://2477033452-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRtV458Onax2rMaEUV2SD%2Fuploads%2FzJekGPx1m1d4d4cwpRHD%2Fimage.png?alt=media&amp;token=f4145469-3954-4c26-9041-eb679811d1c3" alt=""><figcaption></figcaption></figure>

#### A confirmation email will be sent to the owner.

You need to access your email and verify to receive the API Key.

<figure><img src="https://2477033452-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRtV458Onax2rMaEUV2SD%2Fuploads%2F8eKPymGkN0ALbvPRx2i6%2Fimage.png?alt=media&amp;token=88d9587c-6b94-4b80-9357-fed0da090b41" alt=""><figcaption></figcaption></figure>

#### You can revoke and rotate the API key at any time.

<figure><img src="https://2477033452-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRtV458Onax2rMaEUV2SD%2Fuploads%2Fnr1iLjhxJHsAANYSncHl%2Fimage.png?alt=media&amp;token=fb5ec4ab-45f3-4b50-9427-3a91e39cb8dc" alt=""><figcaption></figcaption></figure>

#### Base API URL

`https://preorder.globo.io/shop-api/`&#x20;

The base endpoint for all API requests. Append the corresponding API path to this URL when making requests.

#### Limit&#x20;

`throttle:60,1`&#x20;

Rate Limi&#x74;**:** Maximum **60 requests per minute per client**. Requests exceeding this limit will be rejected with 429 status

***

### Scopes

Each API token is issued one or more **scopes**, which determine which endpoints that token can call. There are 6 scopes, organized as read/write pairs per feature area:

| Scope                 | Description                        | Grants                                                                                                                              |
| --------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `read_preorders`      | Read pre-order offers & products   | View offers, view pre-order product lines                                                                                           |
| `write_preorders`     | Manage pre-order offers & products | Create/update/delete offers, update/delete product lines, toggle continue-selling — **and automatically includes `read_preorders`** |
| `read_coming_soon`    | Read coming soon products          | View coming-soon rules                                                                                                              |
| `write_coming_soon`   | Manage coming soon products        | Create/update/delete coming-soon rules — **and automatically includes `read_coming_soon`**                                          |
| `read_back_in_stock`  | Read back in stock submissions     | View back-in-stock submissions                                                                                                      |
| `write_back_in_stock` | Manage back in stock submissions   | Create/update/delete submissions, send restock notification emails — **and automatically includes `read_back_in_stock`**            |

> **Note:** a `write_x` scope always implies the matching `read_x` scope. For example, a token issued with only `write_preorders` can still call `GET /shop-api/pre-order/list` without needing `read_preorders` granted separately. The reverse is not true: a token with only `read_preorders` will be rejected on any write endpoint (create/update/delete).

#### Scope required per endpoint

| Endpoint                                                                              | Method          | Required scope                                      |
| ------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------- |
| `/back-in-stock/list`, `/back-in-stock/get/{id}`                                      | GET             | `read_back_in_stock`                                |
| `/back-in-stock/create`, `/update`, `/delete`, `/send-notify-restock`                 | POST/PUT/DELETE | `write_back_in_stock`                               |
| `/coming-soon/list`, `/coming-soon/get/{id}`                                          | GET             | `read_coming_soon`                                  |
| `/coming-soon/create`, `/update`, `/delete`                                           | POST/PUT/DELETE | `write_coming_soon`                                 |
| `/pre-order/list`, `/pre-order/get/{id}`                                              | GET             | `read_preorders`                                    |
| `/pre-order/products/list`, `/products/get-products-shopify`                          | GET             | `read_preorders`                                    |
| `/pre-order/create`, `/update`, `/delete`                                             | POST/PUT/DELETE | `write_preorders`                                   |
| `/pre-order/products/update`, `/products/delete`, `/products/toggle-continue-selling` | PUT/DELETE/POST | `write_preorders`                                   |
| `/ping`                                                                               | GET             | No specific scope required — any valid token passes |

#### Missing-scope error (403)

When a token lacks the required scope, the API returns:

```json
{
  "success": false,
  "message": "This API token is missing required scope: write_preorders",
  "required_scopes": ["write_preorders"],
  "missing_scopes": ["write_preorders"]
}
```

* `required_scopes`: every scope this endpoint requires.
* `missing_scopes`: the subset the current token doesn't have (differs from `required_scopes` when the token already holds part of what's needed — e.g. it has `read_preorders` but is missing `write_preorders`).

***

### Test API

{% tabs %}
{% tab title="HTTP" %}

```http
GET /ping HTTP/1.1
Host: preorder.globo.io/shop-api
Authorization: Bearer ••••••••••••••••••••••••••••••••••••
```

{% endtab %}

{% tab title="Javascript - fetch" %}

```js
const myHeaders = new Headers();
myHeaders.append("Authorization", "************");
const requestOptions = {
    method: "GET",
    headers: myHeaders,
    redirect: "follow"
};
fetch("https://preorder.globo.io/shop-api/ping", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));
```

{% endtab %}

{% tab title="PHP" %}

```php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://preorder.globo.io/shop-api/ping',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: ************'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}
{% endtabs %}

<mark style="color:$success;">Success</mark>

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "success": true,
    "message": "API is working"
}
</code></pre>

<mark style="color:$warning;">Unauthorized</mark>

<pre class="language-json"><code class="lang-json">// Missing API token 401
<strong>{"success": false, "message": "Missing API token"}
</strong>// Invalid or revoked API token 401
{"success": false, "message": "Invalid or revoked API token"}
// Insufficient token scope 403
{"success": false, "message": "Insufficient token scope"}
</code></pre>