Issue an access token (v2) — Acme Commerce API

POST /api/v2/auth/tokens v2

No authentication required.

Exchanges an API key pair for a short-lived bearer token. Tokens expire after one hour; request a new one rather than caching indefinitely.

Full URL: https://api.acme.example/api/v2/auth/tokens

Body parameters

Name	Type	Required	Description
key_id	string	yes	The public half of your API key pair.
key_secret	string	yes	The secret half. Never send this from a browser.
scopes	array	no	Defaults to every scope the key is entitled to.

Responses

201 A token you can use as a bearer credential.

422 The key pair was rejected.

Example request

cURL

curl -X POST 'https://api.acme.example/api/v2/auth/tokens' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "key_id": "key id",
    "key_secret": "key secret",
    "scopes": [
        "orders:read"
    ]
}'

JavaScript

const response = await fetch('https://api.acme.example/api/v2/auth/tokens', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "key_id": "key id",
      "key_secret": "key secret",
      "scopes": [
          "orders:read"
      ]
  })
});

const data = await response.json();

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
])->post('https://api.acme.example/api/v2/auth/tokens', [
    'key_id' => 'key id',
    'key_secret' => 'key secret',
    'scopes' => [
        'orders:read',
    ],
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://api.acme.example/api/v2/auth/tokens', [
    'headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'key_id' => 'key id',
        'key_secret' => 'key secret',
        'scopes' => [
            'orders:read',
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true);

Example response

201

{
    "access_token": "act_7f3a9c2e5b1d8406",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scopes": [
        "orders:read",
        "orders:write"
    ]
}

422

{
    "message": "These credentials do not match our records."
}