Authentication models

dataTokenData Required

Response example · TokenData.

Example: {"access_token":"EXAMPLE_ACCESS_TOKEN","expires_at":"2026-01-01T12:15:00Z","expires_in":1800,"permissions":["orders.order:read"],"rate_limits":{"auth_per_minute":1,"read_per_minute":2,"write_per_minute":15},"token_type":"Bearer","warnings":[]}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example"}

Additional fields: No

dataTokenRevokedData Required

Response example · TokenRevokedData.

Example: {"revoked":true}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example-request"}

Additional fields: No

access_tokenStringRequired

Token for the Authorization: Bearer header. Set SHOPENTLY_ACCESS_TOKEN before running the separate example.

Example: "EXAMPLE_ACCESS_TOKEN"

expires_atStringRequired

Expiration time in UTC. Current access restrictions can block the token earlier.

format: "date-time"

Example: "2026-01-01T12:15:00Z"

expires_inIntegerRequired

Actual lifetime in seconds; this example requests 1800. Requests do not extend it. expires_at is the expiration time in UTC.

minimum: 300maximum: 3600

Example: 1800

permissionsArray <String> Required

permissions lists the current effective permissions: the intersection of the key, its author's permissions and the store plan, including active addon grants. Access is checked again on every request.

Example: ["orders.order:read"]

rate_limitsTokenRateLimitsData Required

Engine ≥ 4.143.0. Each token response includes data.rate_limits from the store policy at issuance. All keys share these budgets; a new token does not reset them. A plan change may apply before the token expires.

Example: {"auth_per_minute":1,"read_per_minute":2,"write_per_minute":15}

token_typeStringOptional

Bearer. Authentication scheme for the returned token.

const: "Bearer"

Default: "Bearer"Example: "Bearer"

warningsArray <TokenLifetimeWarning > Required

An integer outside the range uses 900 seconds and returns warnings with token.ttl_out_of_range and a documentation_url on learn.shopently.com. Omission produces no warning; invalid types return 422.

Example: []

Additional fields: No

applied_secondsIntegerOptional

900 s (15 min)

Default: 900

codeStringOptional

token.ttl_out_of_range

const: "token.ttl_out_of_range"

Default: "token.ttl_out_of_range"

documentation_urlStringOptional

https://learn.shopently.com/en/api/docs/authentication/#token-lifetime

Default: "https://learn.shopently.com/en/api/docs/authentication/#token-lifetime"

fieldStringOptional

ttl_seconds

const: "ttl_seconds"

Default: "ttl_seconds"

max_secondsIntegerOptional

3600 s (60 min)

Default: 3600

messageStringOptional

An integer outside the range uses 900 seconds and returns warnings with token.ttl_out_of_range and a documentation_url on learn.shopently.com. Omission produces no warning; invalid types return 422.

Default: "ttl_seconds must be between 300 and 3600 seconds. The default lifetime of 900 seconds was applied."

min_secondsIntegerOptional

300 s (5 min)

Default: 300

Additional fields: No

auth_per_minuteIntegerRequired

Token issuance and revocation requests per minute, including failed authentication attempts. Both operations share the auth budget.

minimum: 0maximum: 1000000

Example: 1

read_per_minuteIntegerRequired

Read requests per minute.

minimum: 0maximum: 1000000

Example: 2

write_per_minuteIntegerRequired

Write requests per minute; this value does not grant write permissions.

minimum: 0maximum: 1000000

Example: 15

Additional fields: No

ttl_secondsIntegerOptional

Optional integer ttl_seconds: 300–3600 seconds (5–60 minutes). If omitted, the default is 900 seconds (15 minutes).

Default: 900Example: 1800

Additional fields: No

access_tokenStringRequired

Send POST /api/v1/auth/revoke with the issuing key in Authorization: ApiKey and the token in JSON access_token. After success, subsequent use returns 401. Repeated, unknown or foreign tokens return the same revoked: true; other keys' tokens are never deleted.

minLength: 1maxLength: 256

Example: "shpt_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Additional fields: No

revokedBooleanOptional

Send POST /api/v1/auth/revoke with the issuing key in Authorization: ApiKey and the token in JSON access_token. After success, subsequent use returns 401. Repeated, unknown or foreign tokens return the same revoked: true; other keys' tokens are never deleted.

const: true

Default: trueExample: true

Additional fields: No