Authentication & Scopes

atouch API uses OAuth 2.1 (client_credentials). Access tokens are JWT (RS256), sent as Authorization: Bearer <token>.

Token endpoint

POST /v1/oauth/token (application/x-www-form-urlencoded)

Parameter	Required	Description
grant_type	✓	client_credentials (also authorization_code / refresh_token)
client_id	✓	Client ID
client_secret	✓	Client secret (confidential)
scope		Requested scopes (defaults to the client's scopes)

Scopes

Scope	Grants access to	PII
read_items	Items / categories / delivery companies	none
read_users	Own shop profile	low
read_orders	Order header, line items, shipments (buyer PII excluded)	none
read_orders_pii	Purchaser / recipient name, address, phone	high
read_customers	Customer LINE identity, tags, orders	low
read_customers_pii	Customer name / address / phone / email / gender	highest
write_reservations	[write] Create / confirm / release inventory reservations	none
write_shipping	[write] Shipping status transitions, tracking number registration / correction	none
write_items	[write] Create/edit items and categories, item images, and stock updates	none

Notes on write scopes

• Write endpoints (write_*) require the Idempotency-Key header. Resending the same key replays the original result (with an Idempotent-Replay: true header).
• Sending a different body with the same key returns 422. Always retry with the identical request.

Least privilege (important)

• A client is granted only the scopes it needs. Requesting an ungranted scope returns 400 invalid_scope (no token is issued).
• PII scopes (*_pii) are granted only to trusted clients.

PII redaction

For tokens without a PII scope, purchaser / recipient / customer-profile fields do not appear in the response (the keys are omitted).

// read_orders only (no purchaser)
{ "data": { "id": "3823", "status": "shipped", "total": {"amount":10000,"currency":"JPY"} } }

// read_orders + read_orders_pii (purchaser present)
{ "data": { "id": "3823", "purchaser": { "last_name": "…", "tel": "…" } } }

Card numbers and payment-gateway tokens are never returned under any scope.

Revoking tokens

Use POST /v1/oauth/revoke (RFC 7009) to revoke a refresh token.